1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[]>
2 <book id="Linux-USB-API">
4 <title>The Linux-USB Host Side API</title>
8 This documentation is free software; you can redistribute
9 it and/or modify it under the terms of the GNU General Public
10 License as published by the Free Software Foundation; either
11 version 2 of the License, or (at your option) any later
16 This program is distributed in the hope that it will be
17 useful, but WITHOUT ANY WARRANTY; without even the implied
18 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
19 See the GNU General Public License for more details.
23 You should have received a copy of the GNU General Public
24 License along with this program; if not, write to the Free
25 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
30 For more details see the file COPYING in the source
31 distribution of Linux.
39 <title>Introduction to USB on Linux</title>
41 <para>A Universal Serial Bus (USB) is used to connect a host,
42 such as a PC or workstation, to a number of peripheral
43 devices. USB uses a tree structure, with the host at the
44 root (the system's master), hubs as interior nodes, and
45 peripheral devices as leaves (and slaves).
46 Modern PCs support several such trees of USB devices, usually
47 one USB 2.0 tree (480 Mbit/sec each) with
48 a few USB 1.1 trees (12 Mbit/sec each) that are used when you
49 connect a USB 1.1 device directly to the machine's "root hub".
52 <para>That master/slave asymmetry was designed in part for
53 ease of use. It is not physically possible to assemble
54 (legal) USB cables incorrectly: all upstream "to-the-host"
55 connectors are the rectangular type, matching the sockets on
56 root hubs, and the downstream type are the squarish type
57 (or they are built in to the peripheral).
58 Software doesn't need to deal with distributed autoconfiguration
59 since the pre-designated master node manages all that.
60 At the electrical level, bus protocol overhead is reduced by
61 eliminating arbitration and moving scheduling into host software.
64 <para>USB 1.0 was announced in January 1996, and was revised
65 as USB 1.1 (with improvements in hub specification and
66 support for interrupt-out transfers) in September 1998.
67 USB 2.0 was released in April 2000, including high speed
68 transfers and transaction translating hubs (used for USB 1.1
69 and 1.0 backward compatibility).
72 <para>USB support was added to Linux early in the 2.2 kernel series
73 shortly before the 2.3 development forked off. Updates
74 from 2.3 were regularly folded back into 2.2 releases, bringing
75 new features such as <filename>/sbin/hotplug</filename> support,
76 more drivers, and more robustness.
77 The 2.5 kernel series continued such improvements, and also
78 worked on USB 2.0 support,
80 better consistency between host controller drivers,
81 API simplification (to make bugs less likely),
82 and providing internal "kerneldoc" documentation.
85 <para>Linux can run inside USB devices as well as on
86 the hosts that control the devices.
87 Because the Linux 2.x USB support evolved to support mass market
88 platforms such as Apple Macintosh or PC-compatible systems,
89 it didn't address design concerns for those types of USB systems.
90 So it can't be used inside mass-market PDAs, or other peripherals.
91 USB device drivers running inside those Linux peripherals
92 don't do the same things as the ones running inside hosts,
93 and so they've been given a different name:
94 they're called <emphasis>gadget drivers</emphasis>.
95 This document does not present gadget drivers.
101 <title>USB Host-Side API Model</title>
103 <para>Within the kernel,
104 host-side drivers for USB devices talk to the "usbcore" APIs.
105 There are two types of public "usbcore" APIs, targetted at two different
106 layers of USB driver. Those are
107 <emphasis>general purpose</emphasis> drivers, exposed through
108 driver frameworks such as block, character, or network devices;
109 and drivers that are <emphasis>part of the core</emphasis>,
110 which are involved in managing a USB bus.
111 Such core drivers include the <emphasis>hub</emphasis> driver,
112 which manages trees of USB devices, and several different kinds
113 of <emphasis>host controller driver (HCD)</emphasis>,
114 which control individual busses.
117 <para>The device model seen by USB drivers is relatively complex.
122 <listitem><para>USB supports four kinds of data transfer
123 (control, bulk, interrupt, and isochronous). Two transfer
124 types use bandwidth as it's available (control and bulk),
125 while the other two types of transfer (interrupt and isochronous)
126 are scheduled to provide guaranteed bandwidth.
129 <listitem><para>The device description model includes one or more
130 "configurations" per device, only one of which is active at a time.
131 Devices that are capable of high speed operation must also support
132 full speed configurations, along with a way to ask about the
133 "other speed" configurations that might be used.
136 <listitem><para>Configurations have one or more "interface", each
137 of which may have "alternate settings". Interfaces may be
138 standardized by USB "Class" specifications, or may be specific to
139 a vendor or device.</para>
141 <para>USB device drivers actually bind to interfaces, not devices.
142 Think of them as "interface drivers", though you
143 may not see many devices where the distinction is important.
144 <emphasis>Most USB devices are simple, with only one configuration,
145 one interface, and one alternate setting.</emphasis>
148 <listitem><para>Interfaces have one or more "endpoints", each of
149 which supports one type and direction of data transfer such as
150 "bulk out" or "interrupt in". The entire configuration may have
151 up to sixteen endpoints in each direction, allocated as needed
152 among all the interfaces.
155 <listitem><para>Data transfer on USB is packetized; each endpoint
156 has a maximum packet size.
157 Drivers must often be aware of conventions such as flagging the end
158 of bulk transfers using "short" (including zero length) packets.
161 <listitem><para>The Linux USB API supports synchronous calls for
162 control and bulk messaging.
163 It also supports asynchnous calls for all kinds of data transfer,
164 using request structures called "URBs" (USB Request Blocks).
169 <para>Accordingly, the USB Core API exposed to device drivers
170 covers quite a lot of territory. You'll probably need to consult
171 the USB 2.0 specification, available online from www.usb.org at
172 no cost, as well as class or device specifications.
175 <para>The only host-side drivers that actually touch hardware
176 (reading/writing registers, handling IRQs, and so on) are the HCDs.
177 In theory, all HCDs provide the same functionality through the same
178 API. In practice, that's becoming more true on the 2.5 kernels,
179 but there are still differences that crop up especially with
180 fault handling. Different controllers don't necessarily report
181 the same aspects of failures, and recovery from faults (including
182 software-induced ones like unlinking an URB) isn't yet fully
184 Device driver authors should make a point of doing disconnect
185 testing (while the device is active) with each different host
186 controller driver, to make sure drivers don't have bugs of
187 their own as well as to make sure they aren't relying on some
188 HCD-specific behavior.
189 (You will need external USB 1.1 and/or
190 USB 2.0 hubs to perform all those tests.)
195 <chapter><title>USB-Standard Types</title>
197 <para>In <filename><linux/usb_ch9.h></filename> you will find
198 the USB data types defined in chapter 9 of the USB specification.
199 These data types are used throughout USB, and in APIs including
200 this host side API, gadget APIs, and usbfs.
203 !Iinclude/linux/usb_ch9.h
207 <chapter><title>Host-Side Data Types and Macros</title>
209 <para>The host side API exposes several layers to drivers, some of
210 which are more necessary than others.
211 These support lifecycle models for host side drivers
212 and devices, and support passing buffers through usbcore to
213 some HCD that performs the I/O for the device driver.
217 !Iinclude/linux/usb.h
221 <chapter><title>USB Core APIs</title>
223 <para>There are two basic I/O models in the USB API.
224 The most elemental one is asynchronous: drivers submit requests
225 in the form of an URB, and the URB's completion callback
226 handle the next step.
227 All USB transfer types support that model, although there
228 are special cases for control URBs (which always have setup
229 and status stages, but may not have a data stage) and
230 isochronous URBs (which allow large packets and include
231 per-packet fault reports).
232 Built on top of that is synchronous API support, where a
233 driver calls a routine that allocates one or more URBs,
234 submits them, and waits until they complete.
235 There are synchronous wrappers for single-buffer control
236 and bulk transfers (which are awkward to use in some
237 driver disconnect scenarios), and for scatterlist based
238 streaming i/o (bulk or interrupt).
241 <para>USB drivers need to provide buffers that can be
242 used for DMA, although they don't necessarily need to
243 provide the DMA mapping themselves.
244 There are APIs to use used when allocating DMA buffers,
245 which can prevent use of bounce buffers on some systems.
246 In some cases, drivers may be able to rely on 64bit DMA
247 to eliminate another kind of bounce buffer.
250 !Edrivers/usb/core/urb.c
251 !Edrivers/usb/core/message.c
252 !Edrivers/usb/core/file.c
253 !Edrivers/usb/core/usb.c
254 !Edrivers/usb/core/hub.c
257 <chapter><title>Host Controller APIs</title>
259 <para>These APIs are only for use by host controller drivers,
260 most of which implement standard register interfaces such as
262 UHCI was one of the first interfaces, designed by Intel and
263 also used by VIA; it doesn't do much in hardware.
264 OHCI was designed later, to have the hardware do more work
265 (bigger transfers, tracking protocol state, and so on).
266 EHCI was designed with USB 2.0; its design has features that
267 resemble OHCI (hardware does much more work) as well as
268 UHCI (some parts of ISO support, TD list processing).
271 <para>There are host controllers other than the "big three",
272 although most PCI based controllers (and a few non-PCI based
273 ones) use one of those interfaces.
274 Not all host controllers use DMA; some use PIO, and there
278 <para>The same basic APIs are available to drivers for all
280 For historical reasons they are in two layers:
281 <structname>struct usb_bus</structname> is a rather thin
282 layer that became available in the 2.2 kernels, while
283 <structname>struct usb_hcd</structname> is a more featureful
284 layer (available in later 2.4 kernels and in 2.5) that
285 lets HCDs share common code, to shrink driver size
286 and significantly reduce hcd-specific behaviors.
289 !Edrivers/usb/core/hcd.c
290 !Edrivers/usb/core/hcd-pci.c
291 !Edrivers/usb/core/buffer.c
295 <title>The USB Filesystem (usbfs)</title>
297 <para>This chapter presents the Linux <emphasis>usbfs</emphasis>.
298 You may prefer to avoid writing new kernel code for your
299 USB driver; that's the problem that usbfs set out to solve.
300 User mode device drivers are usually packaged as applications
301 or libraries, and may use usbfs through some programming library
302 that wraps it. Such libraries include
303 <ulink url="http://libusb.sourceforge.net">libusb</ulink>
305 <ulink url="http://jUSB.sourceforge.net">jUSB</ulink> for Java.
308 <note><title>Unfinished</title>
309 <para>This particular documentation is incomplete,
310 especially with respect to the asynchronous mode.
311 As of kernel 2.5.66 the code and this (new) documentation
312 need to be cross-reviewed.
316 <para>Configure usbfs into Linux kernels by enabling the
317 <emphasis>USB filesystem</emphasis> option (CONFIG_USB_DEVICEFS),
318 and you get basic support for user mode USB device drivers.
319 Until relatively recently it was often (confusingly) called
320 <emphasis>usbdevfs</emphasis> although it wasn't solving what
321 <emphasis>devfs</emphasis> was.
322 Every USB device will appear in usbfs, regardless of whether or
323 not it has a kernel driver; but only devices with kernel drivers
328 <title>What files are in "usbfs"?</title>
330 <para>Conventionally mounted at
331 <filename>/proc/bus/usb</filename>, usbfs
334 <listitem><para><filename>/proc/bus/usb/devices</filename>
336 showing each of the USB devices on known to the kernel,
337 and their configuration descriptors.
338 You can also poll() this to learn about new devices.
340 <listitem><para><filename>/proc/bus/usb/BBB/DDD</filename>
342 exposing the each device's configuration descriptors, and
343 supporting a series of ioctls for making device requests,
344 including I/O to devices. (Purely for access by programs.)
349 <para> Each bus is given a number (BBB) based on when it was
350 enumerated; within each bus, each device is given a similar
352 Those BBB/DDD paths are not "stable" identifiers;
353 expect them to change even if you always leave the devices
354 plugged in to the same hub port.
355 <emphasis>Don't even think of saving these in application
356 configuration files.</emphasis>
357 Stable identifiers are available, for user mode applications
358 that want to use them. HID and networking devices expose
359 these stable IDs, so that for example you can be sure that
360 you told the right UPS to power down its second server.
361 "usbfs" doesn't (yet) expose those IDs.
367 <title>Mounting and Access Control</title>
369 <para>There are a number of mount options for usbfs, which will
370 be of most interest to you if you need to override the default
371 access control policy.
372 That policy is that only root may read or write device files
373 (<filename>/proc/bus/BBB/DDD</filename>) although anyone may read
374 the <filename>devices</filename>
375 or <filename>drivers</filename> files.
376 I/O requests to the device also need the CAP_SYS_RAWIO capability,
379 <para>The significance of that is that by default, all user mode
380 device drivers need super-user privileges.
381 You can change modes or ownership in a driver setup
382 when the device hotplugs, or maye just start the
383 driver right then, as a privileged server (or some activity
385 That's the most secure approach for multi-user systems,
386 but for single user systems ("trusted" by that user)
387 it's more convenient just to grant everyone all access
388 (using the <emphasis>devmode=0666</emphasis> option)
389 so the driver can start whenever it's needed.
392 <para>The mount options for usbfs, usable in /etc/fstab or
393 in command line invocations of <emphasis>mount</emphasis>, are:
397 <term><emphasis>busgid</emphasis>=NNNNN</term>
398 <listitem><para>Controls the GID used for the
400 directories. (Default: 0)</para></listitem></varlistentry>
401 <varlistentry><term><emphasis>busmode</emphasis>=MMM</term>
402 <listitem><para>Controls the file mode used for the
404 directories. (Default: 0555)
405 </para></listitem></varlistentry>
406 <varlistentry><term><emphasis>busuid</emphasis>=NNNNN</term>
407 <listitem><para>Controls the UID used for the
409 directories. (Default: 0)</para></listitem></varlistentry>
411 <varlistentry><term><emphasis>devgid</emphasis>=NNNNN</term>
412 <listitem><para>Controls the GID used for the
413 /proc/bus/usb/BBB/DDD
414 files. (Default: 0)</para></listitem></varlistentry>
415 <varlistentry><term><emphasis>devmode</emphasis>=MMM</term>
416 <listitem><para>Controls the file mode used for the
417 /proc/bus/usb/BBB/DDD
418 files. (Default: 0644)</para></listitem></varlistentry>
419 <varlistentry><term><emphasis>devuid</emphasis>=NNNNN</term>
420 <listitem><para>Controls the UID used for the
421 /proc/bus/usb/BBB/DDD
422 files. (Default: 0)</para></listitem></varlistentry>
424 <varlistentry><term><emphasis>listgid</emphasis>=NNNNN</term>
425 <listitem><para>Controls the GID used for the
426 /proc/bus/usb/devices and drivers files.
427 (Default: 0)</para></listitem></varlistentry>
428 <varlistentry><term><emphasis>listmode</emphasis>=MMM</term>
429 <listitem><para>Controls the file mode used for the
430 /proc/bus/usb/devices and drivers files.
431 (Default: 0444)</para></listitem></varlistentry>
432 <varlistentry><term><emphasis>listuid</emphasis>=NNNNN</term>
433 <listitem><para>Controls the UID used for the
434 /proc/bus/usb/devices and drivers files.
435 (Default: 0)</para></listitem></varlistentry>
440 <para>Note that many Linux distributions hard-wire the mount options
441 for usbfs in their init scripts, such as
442 <filename>/etc/rc.d/rc.sysinit</filename>,
443 rather than making it easy to set this per-system
444 policy in <filename>/etc/fstab</filename>.
450 <title>/proc/bus/usb/devices</title>
452 <para>This file is handy for status viewing tools in user
453 mode, which can scan the text format and ignore most of it.
454 More detailed device status (including class and vendor
455 status) is available from device-specific files.
456 For information about the current format of this file,
458 <filename>Documentation/usb/proc_usb_info.txt</filename>
459 file in your Linux kernel sources.
462 <para>Otherwise the main use for this file from programs
463 is to poll() it to get notifications of usb devices
464 as they're plugged or unplugged.
465 To see what changed, you'd need to read the file and
466 compare "before" and "after" contents, scan the filesystem,
467 or see its hotplug event.
473 <title>/proc/bus/usb/BBB/DDD</title>
475 <para>Use these files in one of these basic ways:
478 <para><emphasis>They can be read,</emphasis>
479 producing first the device descriptor
480 (18 bytes) and then the descriptors for the current configuration.
481 See the USB 2.0 spec for details about those binary data formats.
482 You'll need to convert most multibyte values from little endian
483 format to your native host byte order, although a few of the
484 fields in the device descriptor (both of the BCD-encoded fields,
485 and the vendor and product IDs) will be byteswapped for you.
486 Note that configuration descriptors include descriptors for
487 interfaces, altsettings, endpoints, and maybe additional
491 <para><emphasis>Perform USB operations</emphasis> using
492 <emphasis>ioctl()</emphasis> requests to make endpoint I/O
493 requests (synchronously or asynchronously) or manage
495 These requests need the CAP_SYS_RAWIO capability,
496 as well as filesystem access permissions.
497 Only one ioctl request can be made on one of these
498 device files at a time.
499 This means that if you are synchronously reading an endpoint
500 from one thread, you won't be able to write to a different
501 endpoint from another thread until the read completes.
502 This works for <emphasis>half duplex</emphasis> protocols,
503 but otherwise you'd use asynchronous i/o requests.
510 <title>Life Cycle of User Mode Drivers</title>
512 <para>Such a driver first needs to find a device file
513 for a device it knows how to handle.
514 Maybe it was told about it because a
515 <filename>/sbin/hotplug</filename> event handling agent
516 chose that driver to handle the new device.
517 Or maybe it's an application that scans all the
518 /proc/bus/usb device files, and ignores most devices.
519 In either case, it should <function>read()</function> all
520 the descriptors from the device file,
521 and check them against what it knows how to handle.
522 It might just reject everything except a particular
523 vendor and product ID, or need a more complex policy.
526 <para>Never assume there will only be one such device
527 on the system at a time!
528 If your code can't handle more than one device at
529 a time, at least detect when there's more than one, and
530 have your users choose which device to use.
533 <para>Once your user mode driver knows what device to use,
534 it interacts with it in either of two styles.
535 The simple style is to make only control requests; some
536 devices don't need more complex interactions than those.
537 (An example might be software using vendor-specific control
538 requests for some initialization or configuration tasks,
539 with a kernel driver for the rest.)
542 <para>More likely, you need a more complex style driver:
543 one using non-control endpoints, reading or writing data
544 and claiming exclusive use of an interface.
545 <emphasis>Bulk</emphasis> transfers are easiest to use,
546 but only their sibling <emphasis>interrupt</emphasis> transfers
547 work with low speed devices.
548 Both interrupt and <emphasis>isochronous</emphasis> transfers
549 offer service guarantees because their bandwidth is reserved.
550 Such "periodic" transfers are awkward to use through usbfs,
551 unless you're using the asynchronous calls. However, interrupt
552 transfers can also be used in a synchronous "one shot" style.
555 <para>Your user-mode driver should never need to worry
556 about cleaning up request state when the device is
557 disconnected, although it should close its open file
558 descriptors as soon as it starts seeing the ENODEV
564 <sect1><title>The ioctl() Requests</title>
566 <para>To use these ioctls, you need to include the following
567 headers in your userspace program:
568 <programlisting>#include <linux/usb.h>
569 #include <linux/usbdevice_fs.h>
570 #include <asm/byteorder.h></programlisting>
571 The standard USB device model requests, from "Chapter 9" of
572 the USB 2.0 specification, are automatically included from
573 the <filename><linux/usb_ch9.h></filename> header.
576 <para>Unless noted otherwise, the ioctl requests
578 update the modification time on the usbfs file to which
579 they are applied (unless they fail).
580 A return of zero indicates success; otherwise, a
581 standard USB error code is returned. (These are
583 <filename>Documentation/usb/error-codes.txt</filename>
584 in your kernel sources.)
587 <para>Each of these files multiplexes access to several
588 I/O streams, one per endpoint.
589 Each device has one control endpoint (endpoint zero)
590 which supports a limited RPC style RPC access.
591 Devices are configured
592 by khubd (in the kernel) setting a device-wide
593 <emphasis>configuration</emphasis> that affects things
594 like power consumption and basic functionality.
595 The endpoints are part of USB <emphasis>interfaces</emphasis>,
596 which may have <emphasis>altsettings</emphasis>
597 affecting things like which endpoints are available.
598 Many devices only have a single configuration and interface,
599 so drivers for them will ignore configurations and altsettings.
604 <title>Management/Status Requests</title>
606 <para>A number of usbfs requests don't deal very directly
608 They mostly relate to device management and status.
609 These are all synchronous requests.
614 <varlistentry><term>USBDEVFS_CLAIMINTERFACE</term>
615 <listitem><para>This is used to force usbfs to
616 claim a specific interface,
617 which has not previously been claimed by usbfs or any other
619 The ioctl parameter is an integer holding the number of
620 the interface (bInterfaceNumber from descriptor).
622 Note that if your driver doesn't claim an interface
623 before trying to use one of its endpoints, and no
624 other driver has bound to it, then the interface is
625 automatically claimed by usbfs.
627 This claim will be released by a RELEASEINTERFACE ioctl,
628 or by closing the file descriptor.
629 File modification time is not updated by this request.
630 </para></listitem></varlistentry>
632 <varlistentry><term>USBDEVFS_CONNECTINFO</term>
633 <listitem><para>Says whether the device is lowspeed.
634 The ioctl parameter points to a structure like this:
635 <programlisting>struct usbdevfs_connectinfo {
639 File modification time is not updated by this request.
641 <emphasis>You can't tell whether a "not slow"
642 device is connected at high speed (480 MBit/sec)
643 or just full speed (12 MBit/sec).</emphasis>
644 You should know the devnum value already,
645 it's the DDD value of the device file name.
646 </para></listitem></varlistentry>
648 <varlistentry><term>USBDEVFS_GETDRIVER</term>
649 <listitem><para>Returns the name of the kernel driver
650 bound to a given interface (a string). Parameter
651 is a pointer to this structure, which is modified:
652 <programlisting>struct usbdevfs_getdriver {
653 unsigned int interface;
654 char driver[USBDEVFS_MAXDRIVERNAME + 1];
656 File modification time is not updated by this request.
657 </para></listitem></varlistentry>
659 <varlistentry><term>USBDEVFS_IOCTL</term>
660 <listitem><para>Passes a request from userspace through
661 to a kernel driver that has an ioctl entry in the
662 <emphasis>struct usb_driver</emphasis> it registered.
663 <programlisting>struct usbdevfs_ioctl {
669 /* user mode call looks like this.
670 * 'request' becomes the driver->ioctl() 'code' parameter.
671 * the size of 'param' is encoded in 'request', and that data
672 * is copied to or from the driver->ioctl() 'buf' parameter.
675 usbdev_ioctl (int fd, int ifno, unsigned request, void *param)
677 struct usbdevfs_ioctl wrapper;
680 wrapper.ioctl_code = request;
681 wrapper.data = param;
683 return ioctl (fd, USBDEVFS_IOCTL, &wrapper);
685 File modification time is not updated by this request.
687 This request lets kernel drivers talk to user mode code
688 through filesystem operations even when they don't create
689 a charactor or block special device.
690 It's also been used to do things like ask devices what
691 device special file should be used.
692 Two pre-defined ioctls are used
693 to disconnect and reconnect kernel drivers, so
694 that user mode code can completely manage binding
695 and configuration of devices.
696 </para></listitem></varlistentry>
698 <varlistentry><term>USBDEVFS_RELEASEINTERFACE</term>
699 <listitem><para>This is used to release the claim usbfs
700 made on interface, either implicitly or because of a
701 USBDEVFS_CLAIMINTERFACE call, before the file
702 descriptor is closed.
703 The ioctl parameter is an integer holding the number of
704 the interface (bInterfaceNumber from descriptor);
705 File modification time is not updated by this request.
706 </para><warning><para>
707 <emphasis>No security check is made to ensure
708 that the task which made the claim is the one
709 which is releasing it.
710 This means that user mode driver may interfere
711 other ones. </emphasis>
712 </para></warning></listitem></varlistentry>
714 <varlistentry><term>USBDEVFS_RESETEP</term>
715 <listitem><para>Resets the data toggle value for an endpoint
716 (bulk or interrupt) to DATA0.
717 The ioctl parameter is an integer endpoint number
718 (1 to 15, as identified in the endpoint descriptor),
719 with USB_DIR_IN added if the device's endpoint sends
721 </para><warning><para>
722 <emphasis>Avoid using this request.
723 It should probably be removed.</emphasis>
724 Using it typically means the device and driver will lose
725 toggle synchronization. If you really lost synchronization,
726 you likely need to completely handshake with the device,
727 using a request like CLEAR_HALT
729 </para></warning></listitem></varlistentry>
736 <title>Synchronous I/O Support</title>
738 <para>Synchronous requests involve the kernel blocking
739 until until the user mode request completes, either by
740 finishing successfully or by reporting an error.
741 In most cases this is the simplest way to use usbfs,
742 although as noted above it does prevent performing I/O
743 to more than one endpoint at a time.
748 <varlistentry><term>USBDEVFS_BULK</term>
749 <listitem><para>Issues a bulk read or write request to the
751 The ioctl parameter is a pointer to this structure:
752 <programlisting>struct usbdevfs_bulktransfer {
755 unsigned int timeout; /* in milliseconds */
758 </para><para>The "ep" value identifies a
759 bulk endpoint number (1 to 15, as identified in an endpoint
761 masked with USB_DIR_IN when referring to an endpoint which
762 sends data to the host from the device.
763 The length of the data buffer is identified by "len";
764 Recent kernels support requests up to about 128KBytes.
765 <emphasis>FIXME say how read length is returned,
766 and how short reads are handled.</emphasis>.
767 </para></listitem></varlistentry>
769 <varlistentry><term>USBDEVFS_CLEAR_HALT</term>
770 <listitem><para>Clears endpoint halt (stall) and
771 resets the endpoint toggle. This is only
772 meaningful for bulk or interrupt endpoints.
773 The ioctl parameter is an integer endpoint number
774 (1 to 15, as identified in an endpoint descriptor),
775 masked with USB_DIR_IN when referring to an endpoint which
776 sends data to the host from the device.
778 Use this on bulk or interrupt endpoints which have
779 stalled, returning <emphasis>-EPIPE</emphasis> status
780 to a data transfer request.
781 Do not issue the control request directly, since
782 that could invalidate the host's record of the
784 </para></listitem></varlistentry>
786 <varlistentry><term>USBDEVFS_CONTROL</term>
787 <listitem><para>Issues a control request to the device.
788 The ioctl parameter points to a structure like this:
789 <programlisting>struct usbdevfs_ctrltransfer {
795 __u32 timeout; /* in milliseconds */
799 The first eight bytes of this structure are the contents
800 of the SETUP packet to be sent to the device; see the
801 USB 2.0 specification for details.
802 The bRequestType value is composed by combining a
803 USB_TYPE_* value, a USB_DIR_* value, and a
804 USB_RECIP_* value (from
805 <emphasis><linux/usb.h></emphasis>).
806 If wLength is nonzero, it describes the length of the data
807 buffer, which is either written to the device
808 (USB_DIR_OUT) or read from the device (USB_DIR_IN).
810 At this writing, you can't transfer more than 4 KBytes
811 of data to or from a device; usbfs has a limit, and
812 some host controller drivers have a limit.
813 (That's not usually a problem.)
814 <emphasis>Also</emphasis> there's no way to say it's
815 not OK to get a short read back from the device.
816 </para></listitem></varlistentry>
818 <varlistentry><term>USBDEVFS_RESET</term>
819 <listitem><para>Does a USB level device reset.
820 The ioctl parameter is ignored.
821 After the reset, this rebinds all device interfaces.
822 File modification time is not updated by this request.
823 </para><warning><para>
824 <emphasis>Avoid using this call</emphasis>
825 until some usbcore bugs get fixed,
826 since it does not fully synchronize device, interface,
827 and driver (not just usbfs) state.
828 </para></warning></listitem></varlistentry>
830 <varlistentry><term>USBDEVFS_SETINTERFACE</term>
831 <listitem><para>Sets the alternate setting for an
832 interface. The ioctl parameter is a pointer to a
834 <programlisting>struct usbdevfs_setinterface {
835 unsigned int interface;
836 unsigned int altsetting;
838 File modification time is not updated by this request.
840 Those struct members are from some interface descriptor
841 applying to the the current configuration.
842 The interface number is the bInterfaceNumber value, and
843 the altsetting number is the bAlternateSetting value.
844 (This resets each endpoint in the interface.)
845 </para></listitem></varlistentry>
847 <varlistentry><term>USBDEVFS_SETCONFIGURATION</term>
848 <listitem><para>Issues the
849 <function>usb_set_configuration</function> call
851 The parameter is an integer holding the number of
852 a configuration (bConfigurationValue from descriptor).
853 File modification time is not updated by this request.
854 </para><warning><para>
855 <emphasis>Avoid using this call</emphasis>
856 until some usbcore bugs get fixed,
857 since it does not fully synchronize device, interface,
858 and driver (not just usbfs) state.
859 </para></warning></listitem></varlistentry>
865 <title>Asynchronous I/O Support</title>
867 <para>As mentioned above, there are situations where it may be
868 important to initiate concurrent operations from user mode code.
869 This is particularly important for periodic transfers
870 (interrupt and isochronous), but it can be used for other
871 kinds of USB requests too.
872 In such cases, the asynchronous requests described here
873 are essential. Rather than submitting one request and having
874 the kernel block until it completes, the blocking is separate.
877 <para>These requests are packaged into a structure that
878 resembles the URB used by kernel device drivers.
879 (No POSIX Async I/O support here, sorry.)
880 It identifies the endpoint type (USBDEVFS_URB_TYPE_*),
881 endpoint (number, masked with USB_DIR_IN as appropriate),
882 buffer and length, and a user "context" value serving to
883 uniquely identify each request.
884 (It's usually a pointer to per-request data.)
885 Flags can modify requests (not as many as supported for
889 <para>Each request can specify a realtime signal number
890 (between SIGRTMIN and SIGRTMAX, inclusive) to request a
891 signal be sent when the request completes.
894 <para>When usbfs returns these urbs, the status value
895 is updated, and the buffer may have been modified.
896 Except for isochronous transfers, the actual_length is
897 updated to say how many bytes were transferred; if the
898 USBDEVFS_URB_DISABLE_SPD flag is set
899 ("short packets are not OK"), if fewer bytes were read
900 than were requested then you get an error report.
903 <programlisting>struct usbdevfs_iso_packet_desc {
905 unsigned int actual_length;
909 struct usbdevfs_urb {
911 unsigned char endpoint;
918 int number_of_packets;
922 struct usbdevfs_iso_packet_desc iso_frame_desc[];
925 <para> For these asynchronous requests, the file modification
926 time reflects when the request was initiated.
927 This contrasts with their use with the synchronous requests,
928 where it reflects when requests complete.
933 <varlistentry><term>USBDEVFS_DISCARDURB</term>
935 <emphasis>TBS</emphasis>
936 File modification time is not updated by this request.
938 </para></listitem></varlistentry>
940 <varlistentry><term>USBDEVFS_DISCSIGNAL</term>
942 <emphasis>TBS</emphasis>
943 File modification time is not updated by this request.
945 </para></listitem></varlistentry>
947 <varlistentry><term>USBDEVFS_REAPURB</term>
949 <emphasis>TBS</emphasis>
950 File modification time is not updated by this request.
952 </para></listitem></varlistentry>
954 <varlistentry><term>USBDEVFS_REAPURBNDELAY</term>
956 <emphasis>TBS</emphasis>
957 File modification time is not updated by this request.
959 </para></listitem></varlistentry>
961 <varlistentry><term>USBDEVFS_SUBMITURB</term>
963 <emphasis>TBS</emphasis>
965 </para></listitem></varlistentry>
975 <!-- vim:syntax=sgml:sw=4