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
256 <chapter><title>Host Controller APIs</title>
258 <para>These APIs are only for use by host controller drivers,
259 most of which implement standard register interfaces such as
261 UHCI was one of the first interfaces, designed by Intel and
262 also used by VIA; it doesn't do much in hardware.
263 OHCI was designed later, to have the hardware do more work
264 (bigger transfers, tracking protocol state, and so on).
265 EHCI was designed with USB 2.0; its design has features that
266 resemble OHCI (hardware does much more work) as well as
267 UHCI (some parts of ISO support, TD list processing).
270 <para>There are host controllers other than the "big three",
271 although most PCI based controllers (and a few non-PCI based
272 ones) use one of those interfaces.
273 Not all host controllers use DMA; some use PIO, and there
277 <para>The same basic APIs are available to drivers for all
279 For historical reasons they are in two layers:
280 <structname>struct usb_bus</structname> is a rather thin
281 layer that became available in the 2.2 kernels, while
282 <structname>struct usb_hcd</structname> is a more featureful
283 layer (available in later 2.4 kernels and in 2.5) that
284 lets HCDs share common code, to shrink driver size
285 and significantly reduce hcd-specific behaviors.
288 !Edrivers/usb/core/hcd.c
289 !Edrivers/usb/core/hcd-pci.c
290 !Edrivers/usb/core/buffer.c
294 <title>The USB Filesystem (usbfs)</title>
296 <para>This chapter presents the Linux <emphasis>usbfs</emphasis>.
297 You may prefer to avoid writing new kernel code for your
298 USB driver; that's the problem that usbfs set out to solve.
299 User mode device drivers are usually packaged as applications
300 or libraries, and may use usbfs through some programming library
301 that wraps it. Such libraries include
302 <ulink url="http://libusb.sourceforge.net">libusb</ulink>
304 <ulink url="http://jUSB.sourceforge.net">jUSB</ulink> for Java.
307 <note><title>Unfinished</title>
308 <para>This particular documentation is incomplete,
309 especially with respect to the asynchronous mode.
310 As of kernel 2.5.66 the code and this (new) documentation
311 need to be cross-reviewed.
315 <para>Configure usbfs into Linux kernels by enabling the
316 <emphasis>USB filesystem</emphasis> option (CONFIG_USB_DEVICEFS),
317 and you get basic support for user mode USB device drivers.
318 Until relatively recently it was often (confusingly) called
319 <emphasis>usbdevfs</emphasis> although it wasn't solving what
320 <emphasis>devfs</emphasis> was.
321 Every USB device will appear in usbfs, regardless of whether or
322 not it has a kernel driver; but only devices with kernel drivers
327 <title>What files are in "usbfs"?</title>
329 <para>Conventionally mounted at
330 <filename>/proc/bus/usb</filename>, usbfs
333 <listitem><para><filename>/proc/bus/usb/devices</filename>
335 showing each of the USB devices on known to the kernel,
336 and their configuration descriptors.
337 You can also poll() this to learn about new devices.
339 <listitem><para><filename>/proc/bus/usb/BBB/DDD</filename>
341 exposing the each device's configuration descriptors, and
342 supporting a series of ioctls for making device requests,
343 including I/O to devices. (Purely for access by programs.)
348 <para> Each bus is given a number (BBB) based on when it was
349 enumerated; within each bus, each device is given a similar
351 Those BBB/DDD paths are not "stable" identifiers;
352 expect them to change even if you always leave the devices
353 plugged in to the same hub port.
354 <emphasis>Don't even think of saving these in application
355 configuration files.</emphasis>
356 Stable identifiers are available, for user mode applications
357 that want to use them. HID and networking devices expose
358 these stable IDs, so that for example you can be sure that
359 you told the right UPS to power down its second server.
360 "usbfs" doesn't (yet) expose those IDs.
366 <title>Mounting and Access Control</title>
368 <para>There are a number of mount options for usbfs, which will
369 be of most interest to you if you need to override the default
370 access control policy.
371 That policy is that only root may read or write device files
372 (<filename>/proc/bus/BBB/DDD</filename>) although anyone may read
373 the <filename>devices</filename>
374 or <filename>drivers</filename> files.
375 I/O requests to the device also need the CAP_SYS_RAWIO capability,
378 <para>The significance of that is that by default, all user mode
379 device drivers need super-user privileges.
380 You can change modes or ownership in a driver setup
381 when the device hotplugs, or maye just start the
382 driver right then, as a privileged server (or some activity
384 That's the most secure approach for multi-user systems,
385 but for single user systems ("trusted" by that user)
386 it's more convenient just to grant everyone all access
387 (using the <emphasis>devmode=0666</emphasis> option)
388 so the driver can start whenever it's needed.
391 <para>The mount options for usbfs, usable in /etc/fstab or
392 in command line invocations of <emphasis>mount</emphasis>, are:
396 <term><emphasis>busgid</emphasis>=NNNNN</term>
397 <listitem><para>Controls the GID used for the
399 directories. (Default: 0)</para></listitem></varlistentry>
400 <varlistentry><term><emphasis>busmode</emphasis>=MMM</term>
401 <listitem><para>Controls the file mode used for the
403 directories. (Default: 0555)
404 </para></listitem></varlistentry>
405 <varlistentry><term><emphasis>busuid</emphasis>=NNNNN</term>
406 <listitem><para>Controls the UID used for the
408 directories. (Default: 0)</para></listitem></varlistentry>
410 <varlistentry><term><emphasis>devgid</emphasis>=NNNNN</term>
411 <listitem><para>Controls the GID used for the
412 /proc/bus/usb/BBB/DDD
413 files. (Default: 0)</para></listitem></varlistentry>
414 <varlistentry><term><emphasis>devmode</emphasis>=MMM</term>
415 <listitem><para>Controls the file mode used for the
416 /proc/bus/usb/BBB/DDD
417 files. (Default: 0644)</para></listitem></varlistentry>
418 <varlistentry><term><emphasis>devuid</emphasis>=NNNNN</term>
419 <listitem><para>Controls the UID used for the
420 /proc/bus/usb/BBB/DDD
421 files. (Default: 0)</para></listitem></varlistentry>
423 <varlistentry><term><emphasis>listgid</emphasis>=NNNNN</term>
424 <listitem><para>Controls the GID used for the
425 /proc/bus/usb/devices and drivers files.
426 (Default: 0)</para></listitem></varlistentry>
427 <varlistentry><term><emphasis>listmode</emphasis>=MMM</term>
428 <listitem><para>Controls the file mode used for the
429 /proc/bus/usb/devices and drivers files.
430 (Default: 0444)</para></listitem></varlistentry>
431 <varlistentry><term><emphasis>listuid</emphasis>=NNNNN</term>
432 <listitem><para>Controls the UID used for the
433 /proc/bus/usb/devices and drivers files.
434 (Default: 0)</para></listitem></varlistentry>
439 <para>Note that many Linux distributions hard-wire the mount options
440 for usbfs in their init scripts, such as
441 <filename>/etc/rc.d/rc.sysinit</filename>,
442 rather than making it easy to set this per-system
443 policy in <filename>/etc/fstab</filename>.
449 <title>/proc/bus/usb/devices</title>
451 <para>This file is handy for status viewing tools in user
452 mode, which can scan the text format and ignore most of it.
453 More detailed device status (including class and vendor
454 status) is available from device-specific files.
455 For information about the current format of this file,
457 <filename>Documentation/usb/proc_usb_info.txt</filename>
458 file in your Linux kernel sources.
461 <para>Otherwise the main use for this file from programs
462 is to poll() it to get notifications of usb devices
463 as they're plugged or unplugged.
464 To see what changed, you'd need to read the file and
465 compare "before" and "after" contents, scan the filesystem,
466 or see its hotplug event.
472 <title>/proc/bus/usb/BBB/DDD</title>
474 <para>Use these files in one of these basic ways:
477 <para><emphasis>They can be read,</emphasis>
478 producing first the device descriptor
479 (18 bytes) and then the descriptors for the current configuration.
480 See the USB 2.0 spec for details about those binary data formats.
481 You'll need to convert most multibyte values from little endian
482 format to your native host byte order, although a few of the
483 fields in the device descriptor (both of the BCD-encoded fields,
484 and the vendor and product IDs) will be byteswapped for you.
485 Note that configuration descriptors include descriptors for
486 interfaces, altsettings, endpoints, and maybe additional
490 <para><emphasis>Perform USB operations</emphasis> using
491 <emphasis>ioctl()</emphasis> requests to make endpoint I/O
492 requests (synchronously or asynchronously) or manage
494 These requests need the CAP_SYS_RAWIO capability,
495 as well as filesystem access permissions.
496 Only one ioctl request can be made on one of these
497 device files at a time.
498 This means that if you are synchronously reading an endpoint
499 from one thread, you won't be able to write to a different
500 endpoint from another thread until the read completes.
501 This works for <emphasis>half duplex</emphasis> protocols,
502 but otherwise you'd use asynchronous i/o requests.
509 <title>Life Cycle of User Mode Drivers</title>
511 <para>Such a driver first needs to find a device file
512 for a device it knows how to handle.
513 Maybe it was told about it because a
514 <filename>/sbin/hotplug</filename> event handling agent
515 chose that driver to handle the new device.
516 Or maybe it's an application that scans all the
517 /proc/bus/usb device files, and ignores most devices.
518 In either case, it should <function>read()</function> all
519 the descriptors from the device file,
520 and check them against what it knows how to handle.
521 It might just reject everything except a particular
522 vendor and product ID, or need a more complex policy.
525 <para>Never assume there will only be one such device
526 on the system at a time!
527 If your code can't handle more than one device at
528 a time, at least detect when there's more than one, and
529 have your users choose which device to use.
532 <para>Once your user mode driver knows what device to use,
533 it interacts with it in either of two styles.
534 The simple style is to make only control requests; some
535 devices don't need more complex interactions than those.
536 (An example might be software using vendor-specific control
537 requests for some initialization or configuration tasks,
538 with a kernel driver for the rest.)
541 <para>More likely, you need a more complex style driver:
542 one using non-control endpoints, reading or writing data
543 and claiming exclusive use of an interface.
544 <emphasis>Bulk</emphasis> transfers are easiest to use,
545 but only their sibling <emphasis>interrupt</emphasis> transfers
546 work with low speed devices.
547 Both interrupt and <emphasis>isochronous</emphasis> transfers
548 offer service guarantees because their bandwidth is reserved.
549 Such "periodic" transfers are awkward to use through usbfs,
550 unless you're using the asynchronous calls. However, interrupt
551 transfers can also be used in a synchronous "one shot" style.
554 <para>Your user-mode driver should never need to worry
555 about cleaning up request state when the device is
556 disconnected, although it should close its open file
557 descriptors as soon as it starts seeing the ENODEV
563 <sect1><title>The ioctl() Requests</title>
565 <para>To use these ioctls, you need to include the following
566 headers in your userspace program:
567 <programlisting>#include <linux/usb.h>
568 #include <linux/usbdevice_fs.h>
569 #include <asm/byteorder.h></programlisting>
570 The standard USB device model requests, from "Chapter 9" of
571 the USB 2.0 specification, are automatically included from
572 the <filename><linux/usb_ch9.h></filename> header.
575 <para>Unless noted otherwise, the ioctl requests
577 update the modification time on the usbfs file to which
578 they are applied (unless they fail).
579 A return of zero indicates success; otherwise, a
580 standard USB error code is returned. (These are
582 <filename>Documentation/usb/error-codes.txt</filename>
583 in your kernel sources.)
586 <para>Each of these files multiplexes access to several
587 I/O streams, one per endpoint.
588 Each device has one control endpoint (endpoint zero)
589 which supports a limited RPC style RPC access.
590 Devices are configured
591 by khubd (in the kernel) setting a device-wide
592 <emphasis>configuration</emphasis> that affects things
593 like power consumption and basic functionality.
594 The endpoints are part of USB <emphasis>interfaces</emphasis>,
595 which may have <emphasis>altsettings</emphasis>
596 affecting things like which endpoints are available.
597 Many devices only have a single configuration and interface,
598 so drivers for them will ignore configurations and altsettings.
603 <title>Management/Status Requests</title>
605 <para>A number of usbfs requests don't deal very directly
607 They mostly relate to device management and status.
608 These are all synchronous requests.
613 <varlistentry><term>USBDEVFS_CLAIMINTERFACE</term>
614 <listitem><para>This is used to force usbfs to
615 claim a specific interface,
616 which has not previously been claimed by usbfs or any other
618 The ioctl parameter is an integer holding the number of
619 the interface (bInterfaceNumber from descriptor).
621 Note that if your driver doesn't claim an interface
622 before trying to use one of its endpoints, and no
623 other driver has bound to it, then the interface is
624 automatically claimed by usbfs.
626 This claim will be released by a RELEASEINTERFACE ioctl,
627 or by closing the file descriptor.
628 File modification time is not updated by this request.
629 </para></listitem></varlistentry>
631 <varlistentry><term>USBDEVFS_CONNECTINFO</term>
632 <listitem><para>Says whether the device is lowspeed.
633 The ioctl parameter points to a structure like this:
634 <programlisting>struct usbdevfs_connectinfo {
638 File modification time is not updated by this request.
640 <emphasis>You can't tell whether a "not slow"
641 device is connected at high speed (480 MBit/sec)
642 or just full speed (12 MBit/sec).</emphasis>
643 You should know the devnum value already,
644 it's the DDD value of the device file name.
645 </para></listitem></varlistentry>
647 <varlistentry><term>USBDEVFS_GETDRIVER</term>
648 <listitem><para>Returns the name of the kernel driver
649 bound to a given interface (a string). Parameter
650 is a pointer to this structure, which is modified:
651 <programlisting>struct usbdevfs_getdriver {
652 unsigned int interface;
653 char driver[USBDEVFS_MAXDRIVERNAME + 1];
655 File modification time is not updated by this request.
656 </para></listitem></varlistentry>
658 <varlistentry><term>USBDEVFS_IOCTL</term>
659 <listitem><para>Passes a request from userspace through
660 to a kernel driver that has an ioctl entry in the
661 <emphasis>struct usb_driver</emphasis> it registered.
662 <programlisting>struct usbdevfs_ioctl {
668 /* user mode call looks like this.
669 * 'request' becomes the driver->ioctl() 'code' parameter.
670 * the size of 'param' is encoded in 'request', and that data
671 * is copied to or from the driver->ioctl() 'buf' parameter.
674 usbdev_ioctl (int fd, int ifno, unsigned request, void *param)
676 struct usbdevfs_ioctl wrapper;
679 wrapper.ioctl_code = request;
680 wrapper.data = param;
682 return ioctl (fd, USBDEVFS_IOCTL, &wrapper);
684 File modification time is not updated by this request.
686 This request lets kernel drivers talk to user mode code
687 through filesystem operations even when they don't create
688 a charactor or block special device.
689 It's also been used to do things like ask devices what
690 device special file should be used.
691 Two pre-defined ioctls are used
692 to disconnect and reconnect kernel drivers, so
693 that user mode code can completely manage binding
694 and configuration of devices.
695 </para></listitem></varlistentry>
697 <varlistentry><term>USBDEVFS_RELEASEINTERFACE</term>
698 <listitem><para>This is used to release the claim usbfs
699 made on interface, either implicitly or because of a
700 USBDEVFS_CLAIMINTERFACE call, before the file
701 descriptor is closed.
702 The ioctl parameter is an integer holding the number of
703 the interface (bInterfaceNumber from descriptor);
704 File modification time is not updated by this request.
705 </para><warning><para>
706 <emphasis>No security check is made to ensure
707 that the task which made the claim is the one
708 which is releasing it.
709 This means that user mode driver may interfere
710 other ones. </emphasis>
711 </para></warning></listitem></varlistentry>
713 <varlistentry><term>USBDEVFS_RESETEP</term>
714 <listitem><para>Resets the data toggle value for an endpoint
715 (bulk or interrupt) to DATA0.
716 The ioctl parameter is an integer endpoint number
717 (1 to 15, as identified in the endpoint descriptor),
718 with USB_DIR_IN added if the device's endpoint sends
720 </para><warning><para>
721 <emphasis>Avoid using this request.
722 It should probably be removed.</emphasis>
723 Using it typically means the device and driver will lose
724 toggle synchronization. If you really lost synchronization,
725 you likely need to completely handshake with the device,
726 using a request like CLEAR_HALT
728 </para></warning></listitem></varlistentry>
735 <title>Synchronous I/O Support</title>
737 <para>Synchronous requests involve the kernel blocking
738 until until the user mode request completes, either by
739 finishing successfully or by reporting an error.
740 In most cases this is the simplest way to use usbfs,
741 although as noted above it does prevent performing I/O
742 to more than one endpoint at a time.
747 <varlistentry><term>USBDEVFS_BULK</term>
748 <listitem><para>Issues a bulk read or write request to the
750 The ioctl parameter is a pointer to this structure:
751 <programlisting>struct usbdevfs_bulktransfer {
754 unsigned int timeout; /* in milliseconds */
757 </para><para>The "ep" value identifies a
758 bulk endpoint number (1 to 15, as identified in an endpoint
760 masked with USB_DIR_IN when referring to an endpoint which
761 sends data to the host from the device.
762 The length of the data buffer is identified by "len";
763 Recent kernels support requests up to about 128KBytes.
764 <emphasis>FIXME say how read length is returned,
765 and how short reads are handled.</emphasis>.
766 </para></listitem></varlistentry>
768 <varlistentry><term>USBDEVFS_CLEAR_HALT</term>
769 <listitem><para>Clears endpoint halt (stall) and
770 resets the endpoint toggle. This is only
771 meaningful for bulk or interrupt endpoints.
772 The ioctl parameter is an integer endpoint number
773 (1 to 15, as identified in an endpoint descriptor),
774 masked with USB_DIR_IN when referring to an endpoint which
775 sends data to the host from the device.
777 Use this on bulk or interrupt endpoints which have
778 stalled, returning <emphasis>-EPIPE</emphasis> status
779 to a data transfer request.
780 Do not issue the control request directly, since
781 that could invalidate the host's record of the
783 </para></listitem></varlistentry>
785 <varlistentry><term>USBDEVFS_CONTROL</term>
786 <listitem><para>Issues a control request to the device.
787 The ioctl parameter points to a structure like this:
788 <programlisting>struct usbdevfs_ctrltransfer {
794 __u32 timeout; /* in milliseconds */
798 The first eight bytes of this structure are the contents
799 of the SETUP packet to be sent to the device; see the
800 USB 2.0 specification for details.
801 The bRequestType value is composed by combining a
802 USB_TYPE_* value, a USB_DIR_* value, and a
803 USB_RECIP_* value (from
804 <emphasis><linux/usb.h></emphasis>).
805 If wLength is nonzero, it describes the length of the data
806 buffer, which is either written to the device
807 (USB_DIR_OUT) or read from the device (USB_DIR_IN).
809 At this writing, you can't transfer more than 4 KBytes
810 of data to or from a device; usbfs has a limit, and
811 some host controller drivers have a limit.
812 (That's not usually a problem.)
813 <emphasis>Also</emphasis> there's no way to say it's
814 not OK to get a short read back from the device.
815 </para></listitem></varlistentry>
817 <varlistentry><term>USBDEVFS_RESET</term>
818 <listitem><para>Does a USB level device reset.
819 The ioctl parameter is ignored.
820 After the reset, this rebinds all device interfaces.
821 File modification time is not updated by this request.
822 </para><warning><para>
823 <emphasis>Avoid using this call</emphasis>
824 until some usbcore bugs get fixed,
825 since it does not fully synchronize device, interface,
826 and driver (not just usbfs) state.
827 </para></warning></listitem></varlistentry>
829 <varlistentry><term>USBDEVFS_SETINTERFACE</term>
830 <listitem><para>Sets the alternate setting for an
831 interface. The ioctl parameter is a pointer to a
833 <programlisting>struct usbdevfs_setinterface {
834 unsigned int interface;
835 unsigned int altsetting;
837 File modification time is not updated by this request.
839 Those struct members are from some interface descriptor
840 applying to the the current configuration.
841 The interface number is the bInterfaceNumber value, and
842 the altsetting number is the bAlternateSetting value.
843 (This resets each endpoint in the interface.)
844 </para></listitem></varlistentry>
846 <varlistentry><term>USBDEVFS_SETCONFIGURATION</term>
847 <listitem><para>Issues the
848 <function>usb_set_configuration</function> call
850 The parameter is an integer holding the number of
851 a configuration (bConfigurationValue from descriptor).
852 File modification time is not updated by this request.
853 </para><warning><para>
854 <emphasis>Avoid using this call</emphasis>
855 until some usbcore bugs get fixed,
856 since it does not fully synchronize device, interface,
857 and driver (not just usbfs) state.
858 </para></warning></listitem></varlistentry>
864 <title>Asynchronous I/O Support</title>
866 <para>As mentioned above, there are situations where it may be
867 important to initiate concurrent operations from user mode code.
868 This is particularly important for periodic transfers
869 (interrupt and isochronous), but it can be used for other
870 kinds of USB requests too.
871 In such cases, the asynchronous requests described here
872 are essential. Rather than submitting one request and having
873 the kernel block until it completes, the blocking is separate.
876 <para>These requests are packaged into a structure that
877 resembles the URB used by kernel device drivers.
878 (No POSIX Async I/O support here, sorry.)
879 It identifies the endpoint type (USBDEVFS_URB_TYPE_*),
880 endpoint (number, masked with USB_DIR_IN as appropriate),
881 buffer and length, and a user "context" value serving to
882 uniquely identify each request.
883 (It's usually a pointer to per-request data.)
884 Flags can modify requests (not as many as supported for
888 <para>Each request can specify a realtime signal number
889 (between SIGRTMIN and SIGRTMAX, inclusive) to request a
890 signal be sent when the request completes.
893 <para>When usbfs returns these urbs, the status value
894 is updated, and the buffer may have been modified.
895 Except for isochronous transfers, the actual_length is
896 updated to say how many bytes were transferred; if the
897 USBDEVFS_URB_DISABLE_SPD flag is set
898 ("short packets are not OK"), if fewer bytes were read
899 than were requested then you get an error report.
902 <programlisting>struct usbdevfs_iso_packet_desc {
904 unsigned int actual_length;
908 struct usbdevfs_urb {
910 unsigned char endpoint;
917 int number_of_packets;
921 struct usbdevfs_iso_packet_desc iso_frame_desc[];
924 <para> For these asynchronous requests, the file modification
925 time reflects when the request was initiated.
926 This contrasts with their use with the synchronous requests,
927 where it reflects when requests complete.
932 <varlistentry><term>USBDEVFS_DISCARDURB</term>
934 <emphasis>TBS</emphasis>
935 File modification time is not updated by this request.
937 </para></listitem></varlistentry>
939 <varlistentry><term>USBDEVFS_DISCSIGNAL</term>
941 <emphasis>TBS</emphasis>
942 File modification time is not updated by this request.
944 </para></listitem></varlistentry>
946 <varlistentry><term>USBDEVFS_REAPURB</term>
948 <emphasis>TBS</emphasis>
949 File modification time is not updated by this request.
951 </para></listitem></varlistentry>
953 <varlistentry><term>USBDEVFS_REAPURBNDELAY</term>
955 <emphasis>TBS</emphasis>
956 File modification time is not updated by this request.
958 </para></listitem></varlistentry>
960 <varlistentry><term>USBDEVFS_SUBMITURB</term>
962 <emphasis>TBS</emphasis>
964 </para></listitem></varlistentry>
974 <!-- vim:syntax=sgml:sw=4