Loading...
Note: File does not exist in v6.13.7.
1===========================
2The Linux-USB Host Side API
3===========================
4
5Introduction to USB on Linux
6============================
7
8A Universal Serial Bus (USB) is used to connect a host, such as a PC or
9workstation, to a number of peripheral devices. USB uses a tree
10structure, with the host as the root (the system's master), hubs as
11interior nodes, and peripherals as leaves (and slaves). Modern PCs
12support several such trees of USB devices, usually
13a few USB 3.0 (5 GBit/s) or USB 3.1 (10 GBit/s) and some legacy
14USB 2.0 (480 MBit/s) busses just in case.
15
16That master/slave asymmetry was designed-in for a number of reasons, one
17being ease of use. It is not physically possible to mistake upstream and
18downstream or it does not matter with a type C plug (or they are built into the
19peripheral). Also, the host software doesn't need to deal with
20distributed auto-configuration since the pre-designated master node
21manages all that.
22
23Kernel developers added USB support to Linux early in the 2.2 kernel
24series and have been developing it further since then. Besides support
25for each new generation of USB, various host controllers gained support,
26new drivers for peripherals have been added and advanced features for latency
27measurement and improved power management introduced.
28
29Linux can run inside USB devices as well as on the hosts that control
30the devices. But USB device drivers running inside those peripherals
31don't do the same things as the ones running inside hosts, so they've
32been given a different name: *gadget drivers*. This document does not
33cover gadget drivers.
34
35USB Host-Side API Model
36=======================
37
38Host-side drivers for USB devices talk to the "usbcore" APIs. There are
39two. One is intended for *general-purpose* drivers (exposed through
40driver frameworks), and the other is for drivers that are *part of the
41core*. Such core drivers include the *hub* driver (which manages trees
42of USB devices) and several different kinds of *host controller
43drivers*, which control individual busses.
44
45The device model seen by USB drivers is relatively complex.
46
47- USB supports four kinds of data transfers (control, bulk, interrupt,
48 and isochronous). Two of them (control and bulk) use bandwidth as
49 it's available, while the other two (interrupt and isochronous) are
50 scheduled to provide guaranteed bandwidth.
51
52- The device description model includes one or more "configurations"
53 per device, only one of which is active at a time. Devices are supposed
54 to be capable of operating at lower than their top
55 speeds and may provide a BOS descriptor showing the lowest speed they
56 remain fully operational at.
57
58- From USB 3.0 on configurations have one or more "functions", which
59 provide a common functionality and are grouped together for purposes
60 of power management.
61
62- Configurations or functions have one or more "interfaces", each of which may have
63 "alternate settings". Interfaces may be standardized by USB "Class"
64 specifications, or may be specific to a vendor or device.
65
66 USB device drivers actually bind to interfaces, not devices. Think of
67 them as "interface drivers", though you may not see many devices
68 where the distinction is important. *Most USB devices are simple,
69 with only one function, one configuration, one interface, and one alternate
70 setting.*
71
72- Interfaces have one or more "endpoints", each of which supports one
73 type and direction of data transfer such as "bulk out" or "interrupt
74 in". The entire configuration may have up to sixteen endpoints in
75 each direction, allocated as needed among all the interfaces.
76
77- Data transfer on USB is packetized; each endpoint has a maximum
78 packet size. Drivers must often be aware of conventions such as
79 flagging the end of bulk transfers using "short" (including zero
80 length) packets.
81
82- The Linux USB API supports synchronous calls for control and bulk
83 messages. It also supports asynchronous calls for all kinds of data
84 transfer, using request structures called "URBs" (USB Request
85 Blocks).
86
87Accordingly, the USB Core API exposed to device drivers covers quite a
88lot of territory. You'll probably need to consult the USB 3.0
89specification, available online from www.usb.org at no cost, as well as
90class or device specifications.
91
92The only host-side drivers that actually touch hardware (reading/writing
93registers, handling IRQs, and so on) are the HCDs. In theory, all HCDs
94provide the same functionality through the same API. In practice, that's
95becoming more true, but there are still differences
96that crop up especially with fault handling on the less common controllers.
97Different controllers don't
98necessarily report the same aspects of failures, and recovery from
99faults (including software-induced ones like unlinking an URB) isn't yet
100fully consistent. Device driver authors should make a point of doing
101disconnect testing (while the device is active) with each different host
102controller driver, to make sure drivers don't have bugs of their own as
103well as to make sure they aren't relying on some HCD-specific behavior.
104
105USB-Standard Types
106==================
107
108In ``<linux/usb/ch9.h>`` you will find the USB data types defined in
109chapter 9 of the USB specification. These data types are used throughout
110USB, and in APIs including this host side API, gadget APIs, and usbfs.
111
112.. kernel-doc:: include/linux/usb/ch9.h
113 :internal:
114
115Host-Side Data Types and Macros
116===============================
117
118The host side API exposes several layers to drivers, some of which are
119more necessary than others. These support lifecycle models for host side
120drivers and devices, and support passing buffers through usbcore to some
121HCD that performs the I/O for the device driver.
122
123.. kernel-doc:: include/linux/usb.h
124 :internal:
125
126USB Core APIs
127=============
128
129There are two basic I/O models in the USB API. The most elemental one is
130asynchronous: drivers submit requests in the form of an URB, and the
131URB's completion callback handles the next step. All USB transfer types
132support that model, although there are special cases for control URBs
133(which always have setup and status stages, but may not have a data
134stage) and isochronous URBs (which allow large packets and include
135per-packet fault reports). Built on top of that is synchronous API
136support, where a driver calls a routine that allocates one or more URBs,
137submits them, and waits until they complete. There are synchronous
138wrappers for single-buffer control and bulk transfers (which are awkward
139to use in some driver disconnect scenarios), and for scatterlist based
140streaming i/o (bulk or interrupt).
141
142USB drivers need to provide buffers that can be used for DMA, although
143they don't necessarily need to provide the DMA mapping themselves. There
144are APIs to use used when allocating DMA buffers, which can prevent use
145of bounce buffers on some systems. In some cases, drivers may be able to
146rely on 64bit DMA to eliminate another kind of bounce buffer.
147
148.. kernel-doc:: drivers/usb/core/urb.c
149 :export:
150
151.. kernel-doc:: drivers/usb/core/message.c
152 :export:
153
154.. kernel-doc:: drivers/usb/core/file.c
155 :export:
156
157.. kernel-doc:: drivers/usb/core/driver.c
158 :export:
159
160.. kernel-doc:: drivers/usb/core/usb.c
161 :export:
162
163.. kernel-doc:: drivers/usb/core/hub.c
164 :export:
165
166Host Controller APIs
167====================
168
169These APIs are only for use by host controller drivers, most of which
170implement standard register interfaces such as XHCI, EHCI, OHCI, or UHCI. UHCI
171was one of the first interfaces, designed by Intel and also used by VIA;
172it doesn't do much in hardware. OHCI was designed later, to have the
173hardware do more work (bigger transfers, tracking protocol state, and so
174on). EHCI was designed with USB 2.0; its design has features that
175resemble OHCI (hardware does much more work) as well as UHCI (some parts
176of ISO support, TD list processing). XHCI was designed with USB 3.0. It
177continues to shift support for functionality into hardware.
178
179There are host controllers other than the "big three", although most PCI
180based controllers (and a few non-PCI based ones) use one of those
181interfaces. Not all host controllers use DMA; some use PIO, and there is
182also a simulator and a virtual host controller to pipe USB over the network.
183
184The same basic APIs are available to drivers for all those controllers.
185For historical reasons they are in two layers: :c:type:`struct
186usb_bus <usb_bus>` is a rather thin layer that became available
187in the 2.2 kernels, while :c:type:`struct usb_hcd <usb_hcd>`
188is a more featureful layer
189that lets HCDs share common code, to shrink driver size and
190significantly reduce hcd-specific behaviors.
191
192.. kernel-doc:: drivers/usb/core/hcd.c
193 :export:
194
195.. kernel-doc:: drivers/usb/core/hcd-pci.c
196 :export:
197
198.. kernel-doc:: drivers/usb/core/buffer.c
199 :internal:
200
201The USB Filesystem (usbfs)
202==========================
203
204This chapter presents the Linux *usbfs*. You may prefer to avoid writing
205new kernel code for your USB driver; that's the problem that usbfs set
206out to solve. User mode device drivers are usually packaged as
207applications or libraries, and may use usbfs through some programming
208library that wraps it. Such libraries include
209`libusb <http://libusb.sourceforge.net>`__ for C/C++, and
210`jUSB <http://jUSB.sourceforge.net>`__ for Java.
211
212 **Note**
213
214 This particular documentation is incomplete, especially with respect
215 to the asynchronous mode. As of kernel 2.5.66 the code and this
216 (new) documentation need to be cross-reviewed.
217
218Configure usbfs into Linux kernels by enabling the *USB filesystem*
219option (CONFIG_USB_DEVICEFS), and you get basic support for user mode
220USB device drivers. Until relatively recently it was often (confusingly)
221called *usbdevfs* although it wasn't solving what *devfs* was. Every USB
222device will appear in usbfs, regardless of whether or not it has a
223kernel driver.
224
225What files are in "usbfs"?
226--------------------------
227
228Conventionally mounted at ``/proc/bus/usb``, usbfs features include:
229
230- ``/proc/bus/usb/devices`` ... a text file showing each of the USB
231 devices on known to the kernel, and their configuration descriptors.
232 You can also poll() this to learn about new devices.
233
234- ``/proc/bus/usb/BBB/DDD`` ... magic files exposing the each device's
235 configuration descriptors, and supporting a series of ioctls for
236 making device requests, including I/O to devices. (Purely for access
237 by programs.)
238
239Each bus is given a number (BBB) based on when it was enumerated; within
240each bus, each device is given a similar number (DDD). Those BBB/DDD
241paths are not "stable" identifiers; expect them to change even if you
242always leave the devices plugged in to the same hub port. *Don't even
243think of saving these in application configuration files.* Stable
244identifiers are available, for user mode applications that want to use
245them. HID and networking devices expose these stable IDs, so that for
246example you can be sure that you told the right UPS to power down its
247second server. "usbfs" doesn't (yet) expose those IDs.
248
249Mounting and Access Control
250---------------------------
251
252There are a number of mount options for usbfs, which will be of most
253interest to you if you need to override the default access control
254policy. That policy is that only root may read or write device files
255(``/proc/bus/BBB/DDD``) although anyone may read the ``devices`` or
256``drivers`` files. I/O requests to the device also need the
257CAP_SYS_RAWIO capability,
258
259The significance of that is that by default, all user mode device
260drivers need super-user privileges. You can change modes or ownership in
261a driver setup when the device hotplugs, or maye just start the driver
262right then, as a privileged server (or some activity within one). That's
263the most secure approach for multi-user systems, but for single user
264systems ("trusted" by that user) it's more convenient just to grant
265everyone all access (using the *devmode=0666* option) so the driver can
266start whenever it's needed.
267
268The mount options for usbfs, usable in /etc/fstab or in command line
269invocations of *mount*, are:
270
271*busgid*\ =NNNNN
272 Controls the GID used for the /proc/bus/usb/BBB directories.
273 (Default: 0)
274
275*busmode*\ =MMM
276 Controls the file mode used for the /proc/bus/usb/BBB directories.
277 (Default: 0555)
278
279*busuid*\ =NNNNN
280 Controls the UID used for the /proc/bus/usb/BBB directories.
281 (Default: 0)
282
283*devgid*\ =NNNNN
284 Controls the GID used for the /proc/bus/usb/BBB/DDD files. (Default:
285 0)
286
287*devmode*\ =MMM
288 Controls the file mode used for the /proc/bus/usb/BBB/DDD files.
289 (Default: 0644)
290
291*devuid*\ =NNNNN
292 Controls the UID used for the /proc/bus/usb/BBB/DDD files. (Default:
293 0)
294
295*listgid*\ =NNNNN
296 Controls the GID used for the /proc/bus/usb/devices and drivers
297 files. (Default: 0)
298
299*listmode*\ =MMM
300 Controls the file mode used for the /proc/bus/usb/devices and
301 drivers files. (Default: 0444)
302
303*listuid*\ =NNNNN
304 Controls the UID used for the /proc/bus/usb/devices and drivers
305 files. (Default: 0)
306
307Note that many Linux distributions hard-wire the mount options for usbfs
308in their init scripts, such as ``/etc/rc.d/rc.sysinit``, rather than
309making it easy to set this per-system policy in ``/etc/fstab``.
310
311/proc/bus/usb/devices
312---------------------
313
314This file is handy for status viewing tools in user mode, which can scan
315the text format and ignore most of it. More detailed device status
316(including class and vendor status) is available from device-specific
317files. For information about the current format of this file, see the
318``Documentation/usb/proc_usb_info.txt`` file in your Linux kernel
319sources.
320
321This file, in combination with the poll() system call, can also be used
322to detect when devices are added or removed:
323
324::
325
326 int fd;
327 struct pollfd pfd;
328
329 fd = open("/proc/bus/usb/devices", O_RDONLY);
330 pfd = { fd, POLLIN, 0 };
331 for (;;) {
332 /* The first time through, this call will return immediately. */
333 poll(&pfd, 1, -1);
334
335 /* To see what's changed, compare the file's previous and current
336 contents or scan the filesystem. (Scanning is more precise.) */
337 }
338
339Note that this behavior is intended to be used for informational and
340debug purposes. It would be more appropriate to use programs such as
341udev or HAL to initialize a device or start a user-mode helper program,
342for instance.
343
344/proc/bus/usb/BBB/DDD
345---------------------
346
347Use these files in one of these basic ways:
348
349*They can be read,* producing first the device descriptor (18 bytes) and
350then the descriptors for the current configuration. See the USB 2.0 spec
351for details about those binary data formats. You'll need to convert most
352multibyte values from little endian format to your native host byte
353order, although a few of the fields in the device descriptor (both of
354the BCD-encoded fields, and the vendor and product IDs) will be
355byteswapped for you. Note that configuration descriptors include
356descriptors for interfaces, altsettings, endpoints, and maybe additional
357class descriptors.
358
359*Perform USB operations* using *ioctl()* requests to make endpoint I/O
360requests (synchronously or asynchronously) or manage the device. These
361requests need the CAP_SYS_RAWIO capability, as well as filesystem
362access permissions. Only one ioctl request can be made on one of these
363device files at a time. This means that if you are synchronously reading
364an endpoint from one thread, you won't be able to write to a different
365endpoint from another thread until the read completes. This works for
366*half duplex* protocols, but otherwise you'd use asynchronous i/o
367requests.
368
369Life Cycle of User Mode Drivers
370-------------------------------
371
372Such a driver first needs to find a device file for a device it knows
373how to handle. Maybe it was told about it because a ``/sbin/hotplug``
374event handling agent chose that driver to handle the new device. Or
375maybe it's an application that scans all the /proc/bus/usb device files,
376and ignores most devices. In either case, it should :c:func:`read()`
377all the descriptors from the device file, and check them against what it
378knows how to handle. It might just reject everything except a particular
379vendor and product ID, or need a more complex policy.
380
381Never assume there will only be one such device on the system at a time!
382If your code can't handle more than one device at a time, at least
383detect when there's more than one, and have your users choose which
384device to use.
385
386Once your user mode driver knows what device to use, it interacts with
387it in either of two styles. The simple style is to make only control
388requests; some devices don't need more complex interactions than those.
389(An example might be software using vendor-specific control requests for
390some initialization or configuration tasks, with a kernel driver for the
391rest.)
392
393More likely, you need a more complex style driver: one using non-control
394endpoints, reading or writing data and claiming exclusive use of an
395interface. *Bulk* transfers are easiest to use, but only their sibling
396*interrupt* transfers work with low speed devices. Both interrupt and
397*isochronous* transfers offer service guarantees because their bandwidth
398is reserved. Such "periodic" transfers are awkward to use through usbfs,
399unless you're using the asynchronous calls. However, interrupt transfers
400can also be used in a synchronous "one shot" style.
401
402Your user-mode driver should never need to worry about cleaning up
403request state when the device is disconnected, although it should close
404its open file descriptors as soon as it starts seeing the ENODEV errors.
405
406The ioctl() Requests
407--------------------
408
409To use these ioctls, you need to include the following headers in your
410userspace program:
411
412::
413
414 #include <linux/usb.h>
415 #include <linux/usbdevice_fs.h>
416 #include <asm/byteorder.h>
417
418The standard USB device model requests, from "Chapter 9" of the USB 2.0
419specification, are automatically included from the ``<linux/usb/ch9.h>``
420header.
421
422Unless noted otherwise, the ioctl requests described here will update
423the modification time on the usbfs file to which they are applied
424(unless they fail). A return of zero indicates success; otherwise, a
425standard USB error code is returned. (These are documented in
426``Documentation/usb/error-codes.txt`` in your kernel sources.)
427
428Each of these files multiplexes access to several I/O streams, one per
429endpoint. Each device has one control endpoint (endpoint zero) which
430supports a limited RPC style RPC access. Devices are configured by
431hub_wq (in the kernel) setting a device-wide *configuration* that
432affects things like power consumption and basic functionality. The
433endpoints are part of USB *interfaces*, which may have *altsettings*
434affecting things like which endpoints are available. Many devices only
435have a single configuration and interface, so drivers for them will
436ignore configurations and altsettings.
437
438Management/Status Requests
439~~~~~~~~~~~~~~~~~~~~~~~~~~
440
441A number of usbfs requests don't deal very directly with device I/O.
442They mostly relate to device management and status. These are all
443synchronous requests.
444
445USBDEVFS_CLAIMINTERFACE
446 This is used to force usbfs to claim a specific interface, which has
447 not previously been claimed by usbfs or any other kernel driver. The
448 ioctl parameter is an integer holding the number of the interface
449 (bInterfaceNumber from descriptor).
450
451 Note that if your driver doesn't claim an interface before trying to
452 use one of its endpoints, and no other driver has bound to it, then
453 the interface is automatically claimed by usbfs.
454
455 This claim will be released by a RELEASEINTERFACE ioctl, or by
456 closing the file descriptor. File modification time is not updated
457 by this request.
458
459USBDEVFS_CONNECTINFO
460 Says whether the device is lowspeed. The ioctl parameter points to a
461 structure like this:
462
463 ::
464
465 struct usbdevfs_connectinfo {
466 unsigned int devnum;
467 unsigned char slow;
468 };
469
470 File modification time is not updated by this request.
471
472 *You can't tell whether a "not slow" device is connected at high
473 speed (480 MBit/sec) or just full speed (12 MBit/sec).* You should
474 know the devnum value already, it's the DDD value of the device file
475 name.
476
477USBDEVFS_GETDRIVER
478 Returns the name of the kernel driver bound to a given interface (a
479 string). Parameter is a pointer to this structure, which is
480 modified:
481
482 ::
483
484 struct usbdevfs_getdriver {
485 unsigned int interface;
486 char driver[USBDEVFS_MAXDRIVERNAME + 1];
487 };
488
489 File modification time is not updated by this request.
490
491USBDEVFS_IOCTL
492 Passes a request from userspace through to a kernel driver that has
493 an ioctl entry in the *struct usb_driver* it registered.
494
495 ::
496
497 struct usbdevfs_ioctl {
498 int ifno;
499 int ioctl_code;
500 void *data;
501 };
502
503 /* user mode call looks like this.
504 * 'request' becomes the driver->ioctl() 'code' parameter.
505 * the size of 'param' is encoded in 'request', and that data
506 * is copied to or from the driver->ioctl() 'buf' parameter.
507 */
508 static int
509 usbdev_ioctl (int fd, int ifno, unsigned request, void *param)
510 {
511 struct usbdevfs_ioctl wrapper;
512
513 wrapper.ifno = ifno;
514 wrapper.ioctl_code = request;
515 wrapper.data = param;
516
517 return ioctl (fd, USBDEVFS_IOCTL, &wrapper);
518 }
519
520 File modification time is not updated by this request.
521
522 This request lets kernel drivers talk to user mode code through
523 filesystem operations even when they don't create a character or
524 block special device. It's also been used to do things like ask
525 devices what device special file should be used. Two pre-defined
526 ioctls are used to disconnect and reconnect kernel drivers, so that
527 user mode code can completely manage binding and configuration of
528 devices.
529
530USBDEVFS_RELEASEINTERFACE
531 This is used to release the claim usbfs made on interface, either
532 implicitly or because of a USBDEVFS_CLAIMINTERFACE call, before the
533 file descriptor is closed. The ioctl parameter is an integer holding
534 the number of the interface (bInterfaceNumber from descriptor); File
535 modification time is not updated by this request.
536
537 **Warning**
538
539 *No security check is made to ensure that the task which made
540 the claim is the one which is releasing it. This means that user
541 mode driver may interfere other ones.*
542
543USBDEVFS_RESETEP
544 Resets the data toggle value for an endpoint (bulk or interrupt) to
545 DATA0. The ioctl parameter is an integer endpoint number (1 to 15,
546 as identified in the endpoint descriptor), with USB_DIR_IN added
547 if the device's endpoint sends data to the host.
548
549 **Warning**
550
551 *Avoid using this request. It should probably be removed.* Using
552 it typically means the device and driver will lose toggle
553 synchronization. If you really lost synchronization, you likely
554 need to completely handshake with the device, using a request
555 like CLEAR_HALT or SET_INTERFACE.
556
557USBDEVFS_DROP_PRIVILEGES
558 This is used to relinquish the ability to do certain operations
559 which are considered to be privileged on a usbfs file descriptor.
560 This includes claiming arbitrary interfaces, resetting a device on
561 which there are currently claimed interfaces from other users, and
562 issuing USBDEVFS_IOCTL calls. The ioctl parameter is a 32 bit mask
563 of interfaces the user is allowed to claim on this file descriptor.
564 You may issue this ioctl more than one time to narrow said mask.
565
566Synchronous I/O Support
567~~~~~~~~~~~~~~~~~~~~~~~
568
569Synchronous requests involve the kernel blocking until the user mode
570request completes, either by finishing successfully or by reporting an
571error. In most cases this is the simplest way to use usbfs, although as
572noted above it does prevent performing I/O to more than one endpoint at
573a time.
574
575USBDEVFS_BULK
576 Issues a bulk read or write request to the device. The ioctl
577 parameter is a pointer to this structure:
578
579 ::
580
581 struct usbdevfs_bulktransfer {
582 unsigned int ep;
583 unsigned int len;
584 unsigned int timeout; /* in milliseconds */
585 void *data;
586 };
587
588 The "ep" value identifies a bulk endpoint number (1 to 15, as
589 identified in an endpoint descriptor), masked with USB_DIR_IN when
590 referring to an endpoint which sends data to the host from the
591 device. The length of the data buffer is identified by "len"; Recent
592 kernels support requests up to about 128KBytes. *FIXME say how read
593 length is returned, and how short reads are handled.*.
594
595USBDEVFS_CLEAR_HALT
596 Clears endpoint halt (stall) and resets the endpoint toggle. This is
597 only meaningful for bulk or interrupt endpoints. The ioctl parameter
598 is an integer endpoint number (1 to 15, as identified in an endpoint
599 descriptor), masked with USB_DIR_IN when referring to an endpoint
600 which sends data to the host from the device.
601
602 Use this on bulk or interrupt endpoints which have stalled,
603 returning *-EPIPE* status to a data transfer request. Do not issue
604 the control request directly, since that could invalidate the host's
605 record of the data toggle.
606
607USBDEVFS_CONTROL
608 Issues a control request to the device. The ioctl parameter points
609 to a structure like this:
610
611 ::
612
613 struct usbdevfs_ctrltransfer {
614 __u8 bRequestType;
615 __u8 bRequest;
616 __u16 wValue;
617 __u16 wIndex;
618 __u16 wLength;
619 __u32 timeout; /* in milliseconds */
620 void *data;
621 };
622
623 The first eight bytes of this structure are the contents of the
624 SETUP packet to be sent to the device; see the USB 2.0 specification
625 for details. The bRequestType value is composed by combining a
626 USB_TYPE_\* value, a USB_DIR_\* value, and a USB_RECIP_\*
627 value (from *<linux/usb.h>*). If wLength is nonzero, it describes
628 the length of the data buffer, which is either written to the device
629 (USB_DIR_OUT) or read from the device (USB_DIR_IN).
630
631 At this writing, you can't transfer more than 4 KBytes of data to or
632 from a device; usbfs has a limit, and some host controller drivers
633 have a limit. (That's not usually a problem.) *Also* there's no way
634 to say it's not OK to get a short read back from the device.
635
636USBDEVFS_RESET
637 Does a USB level device reset. The ioctl parameter is ignored. After
638 the reset, this rebinds all device interfaces. File modification
639 time is not updated by this request.
640
641 **Warning**
642
643 *Avoid using this call* until some usbcore bugs get fixed, since
644 it does not fully synchronize device, interface, and driver (not
645 just usbfs) state.
646
647USBDEVFS_SETINTERFACE
648 Sets the alternate setting for an interface. The ioctl parameter is
649 a pointer to a structure like this:
650
651 ::
652
653 struct usbdevfs_setinterface {
654 unsigned int interface;
655 unsigned int altsetting;
656 };
657
658 File modification time is not updated by this request.
659
660 Those struct members are from some interface descriptor applying to
661 the current configuration. The interface number is the
662 bInterfaceNumber value, and the altsetting number is the
663 bAlternateSetting value. (This resets each endpoint in the
664 interface.)
665
666USBDEVFS_SETCONFIGURATION
667 Issues the :c:func:`usb_set_configuration()` call for the
668 device. The parameter is an integer holding the number of a
669 configuration (bConfigurationValue from descriptor). File
670 modification time is not updated by this request.
671
672 **Warning**
673
674 *Avoid using this call* until some usbcore bugs get fixed, since
675 it does not fully synchronize device, interface, and driver (not
676 just usbfs) state.
677
678Asynchronous I/O Support
679~~~~~~~~~~~~~~~~~~~~~~~~
680
681As mentioned above, there are situations where it may be important to
682initiate concurrent operations from user mode code. This is particularly
683important for periodic transfers (interrupt and isochronous), but it can
684be used for other kinds of USB requests too. In such cases, the
685asynchronous requests described here are essential. Rather than
686submitting one request and having the kernel block until it completes,
687the blocking is separate.
688
689These requests are packaged into a structure that resembles the URB used
690by kernel device drivers. (No POSIX Async I/O support here, sorry.) It
691identifies the endpoint type (USBDEVFS_URB_TYPE_\*), endpoint
692(number, masked with USB_DIR_IN as appropriate), buffer and length,
693and a user "context" value serving to uniquely identify each request.
694(It's usually a pointer to per-request data.) Flags can modify requests
695(not as many as supported for kernel drivers).
696
697Each request can specify a realtime signal number (between SIGRTMIN and
698SIGRTMAX, inclusive) to request a signal be sent when the request
699completes.
700
701When usbfs returns these urbs, the status value is updated, and the
702buffer may have been modified. Except for isochronous transfers, the
703actual_length is updated to say how many bytes were transferred; if the
704USBDEVFS_URB_DISABLE_SPD flag is set ("short packets are not OK"), if
705fewer bytes were read than were requested then you get an error report.
706
707::
708
709 struct usbdevfs_iso_packet_desc {
710 unsigned int length;
711 unsigned int actual_length;
712 unsigned int status;
713 };
714
715 struct usbdevfs_urb {
716 unsigned char type;
717 unsigned char endpoint;
718 int status;
719 unsigned int flags;
720 void *buffer;
721 int buffer_length;
722 int actual_length;
723 int start_frame;
724 int number_of_packets;
725 int error_count;
726 unsigned int signr;
727 void *usercontext;
728 struct usbdevfs_iso_packet_desc iso_frame_desc[];
729 };
730
731For these asynchronous requests, the file modification time reflects
732when the request was initiated. This contrasts with their use with the
733synchronous requests, where it reflects when requests complete.
734
735USBDEVFS_DISCARDURB
736 *TBS* File modification time is not updated by this request.
737
738USBDEVFS_DISCSIGNAL
739 *TBS* File modification time is not updated by this request.
740
741USBDEVFS_REAPURB
742 *TBS* File modification time is not updated by this request.
743
744USBDEVFS_REAPURBNDELAY
745 *TBS* File modification time is not updated by this request.
746
747USBDEVFS_SUBMITURB
748 *TBS*