1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
5 <book id="Linux-USB-API">
7 <title>The Linux-USB Host Side API</title>
11 This documentation is free software; you can redistribute
12 it and/or modify it under the terms of the GNU General Public
13 License as published by the Free Software Foundation; either
14 version 2 of the License, or (at your option) any later
19 This program is distributed in the hope that it will be
20 useful, but WITHOUT ANY WARRANTY; without even the implied
21 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
22 See the GNU General Public License for more details.
26 You should have received a copy of the GNU General Public
27 License along with this program; if not, write to the Free
28 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
33 For more details see the file COPYING in the source
34 distribution of Linux.
42 <title>Introduction to USB on Linux</title>
44 <para>A Universal Serial Bus (USB) is used to connect a host,
45 such as a PC or workstation, to a number of peripheral
46 devices. USB uses a tree structure, with the host as the
47 root (the system's master), hubs as interior nodes, and
48 peripherals as leaves (and slaves).
49 Modern PCs support several such trees of USB devices, usually
50 one USB 2.0 tree (480 Mbit/sec each) with
51 a few USB 1.1 trees (12 Mbit/sec each) that are used when you
52 connect a USB 1.1 device directly to the machine's "root hub".
55 <para>That master/slave asymmetry was designed-in for a number of
56 reasons, one being ease of use. It is not physically possible to
57 assemble (legal) USB cables incorrectly: all upstream "to the host"
58 connectors are the rectangular type (matching the sockets on
59 root hubs), and all downstream connectors are the squarish type
60 (or they are built into the peripheral).
61 Also, the host software doesn't need to deal with distributed
62 auto-configuration since the pre-designated master node manages all that.
63 And finally, at the electrical level, bus protocol overhead is reduced by
64 eliminating arbitration and moving scheduling into the host software.
67 <para>USB 1.0 was announced in January 1996 and was revised
68 as USB 1.1 (with improvements in hub specification and
69 support for interrupt-out transfers) in September 1998.
70 USB 2.0 was released in April 2000, adding high-speed
71 transfers and transaction-translating hubs (used for USB 1.1
72 and 1.0 backward compatibility).
75 <para>Kernel developers added USB support to Linux early in the 2.2 kernel
76 series, shortly before 2.3 development forked. Updates from 2.3 were
77 regularly folded back into 2.2 releases, which improved reliability and
78 brought <filename>/sbin/hotplug</filename> support as well more drivers.
79 Such improvements were continued in the 2.5 kernel series, where they added
80 USB 2.0 support, improved performance, and made the host controller drivers
81 (HCDs) more consistent. They also simplified the API (to make bugs less
82 likely) and added internal "kerneldoc" documentation.
85 <para>Linux can run inside USB devices as well as on
86 the hosts that control the devices.
87 But USB device drivers running inside those peripherals
88 don't do the same things as the ones running inside hosts,
89 so they've been given a different name:
90 <emphasis>gadget drivers</emphasis>.
91 This document does not cover gadget drivers.
97 <title>USB Host-Side API Model</title>
99 <para>Host-side drivers for USB devices talk to the "usbcore" APIs.
100 There are two. One is intended for
101 <emphasis>general-purpose</emphasis> drivers (exposed through
102 driver frameworks), and the other is for drivers that are
103 <emphasis>part of the core</emphasis>.
104 Such core drivers include the <emphasis>hub</emphasis> driver
105 (which manages trees of USB devices) and several different kinds
106 of <emphasis>host controller drivers</emphasis>,
107 which control individual busses.
110 <para>The device model seen by USB drivers is relatively complex.
115 <listitem><para>USB supports four kinds of data transfers
116 (control, bulk, interrupt, and isochronous). Two of them (control
117 and bulk) use bandwidth as it's available,
118 while the other two (interrupt and isochronous)
119 are scheduled to provide guaranteed bandwidth.
122 <listitem><para>The device description model includes one or more
123 "configurations" per device, only one of which is active at a time.
124 Devices that are capable of high-speed operation must also support
125 full-speed configurations, along with a way to ask about the
126 "other speed" configurations which might be used.
129 <listitem><para>Configurations have one or more "interfaces", each
130 of which may have "alternate settings". Interfaces may be
131 standardized by USB "Class" specifications, or may be specific to
132 a vendor or device.</para>
134 <para>USB device drivers actually bind to interfaces, not devices.
135 Think of them as "interface drivers", though you
136 may not see many devices where the distinction is important.
137 <emphasis>Most USB devices are simple, with only one configuration,
138 one interface, and one alternate setting.</emphasis>
141 <listitem><para>Interfaces have one or more "endpoints", each of
142 which supports one type and direction of data transfer such as
143 "bulk out" or "interrupt in". The entire configuration may have
144 up to sixteen endpoints in each direction, allocated as needed
145 among all the interfaces.
148 <listitem><para>Data transfer on USB is packetized; each endpoint
149 has a maximum packet size.
150 Drivers must often be aware of conventions such as flagging the end
151 of bulk transfers using "short" (including zero length) packets.
154 <listitem><para>The Linux USB API supports synchronous calls for
155 control and bulk messages.
156 It also supports asynchnous calls for all kinds of data transfer,
157 using request structures called "URBs" (USB Request Blocks).
162 <para>Accordingly, the USB Core API exposed to device drivers
163 covers quite a lot of territory. You'll probably need to consult
164 the USB 2.0 specification, available online from www.usb.org at
165 no cost, as well as class or device specifications.
168 <para>The only host-side drivers that actually touch hardware
169 (reading/writing registers, handling IRQs, and so on) are the HCDs.
170 In theory, all HCDs provide the same functionality through the same
171 API. In practice, that's becoming more true on the 2.5 kernels,
172 but there are still differences that crop up especially with
173 fault handling. Different controllers don't necessarily report
174 the same aspects of failures, and recovery from faults (including
175 software-induced ones like unlinking an URB) isn't yet fully
177 Device driver authors should make a point of doing disconnect
178 testing (while the device is active) with each different host
179 controller driver, to make sure drivers don't have bugs of
180 their own as well as to make sure they aren't relying on some
181 HCD-specific behavior.
182 (You will need external USB 1.1 and/or
183 USB 2.0 hubs to perform all those tests.)
188 <chapter><title>USB-Standard Types</title>
190 <para>In <filename><linux/usb_ch9.h></filename> you will find
191 the USB data types defined in chapter 9 of the USB specification.
192 These data types are used throughout USB, and in APIs including
193 this host side API, gadget APIs, and usbfs.
196 !Iinclude/linux/usb_ch9.h
200 <chapter><title>Host-Side Data Types and Macros</title>
202 <para>The host side API exposes several layers to drivers, some of
203 which are more necessary than others.
204 These support lifecycle models for host side drivers
205 and devices, and support passing buffers through usbcore to
206 some HCD that performs the I/O for the device driver.
210 !Iinclude/linux/usb.h
214 <chapter><title>USB Core APIs</title>
216 <para>There are two basic I/O models in the USB API.
217 The most elemental one is asynchronous: drivers submit requests
218 in the form of an URB, and the URB's completion callback
219 handle the next step.
220 All USB transfer types support that model, although there
221 are special cases for control URBs (which always have setup
222 and status stages, but may not have a data stage) and
223 isochronous URBs (which allow large packets and include
224 per-packet fault reports).
225 Built on top of that is synchronous API support, where a
226 driver calls a routine that allocates one or more URBs,
227 submits them, and waits until they complete.
228 There are synchronous wrappers for single-buffer control
229 and bulk transfers (which are awkward to use in some
230 driver disconnect scenarios), and for scatterlist based
231 streaming i/o (bulk or interrupt).
234 <para>USB drivers need to provide buffers that can be
235 used for DMA, although they don't necessarily need to
236 provide the DMA mapping themselves.
237 There are APIs to use used when allocating DMA buffers,
238 which can prevent use of bounce buffers on some systems.
239 In some cases, drivers may be able to rely on 64bit DMA
240 to eliminate another kind of bounce buffer.
243 !Edrivers/usb/core/urb.c
244 !Edrivers/usb/core/message.c
245 !Edrivers/usb/core/file.c
246 !Edrivers/usb/core/driver.c
247 !Edrivers/usb/core/usb.c
248 !Edrivers/usb/core/hub.c
251 <chapter><title>Host Controller APIs</title>
253 <para>These APIs are only for use by host controller drivers,
254 most of which implement standard register interfaces such as
256 UHCI was one of the first interfaces, designed by Intel and
257 also used by VIA; it doesn't do much in hardware.
258 OHCI was designed later, to have the hardware do more work
259 (bigger transfers, tracking protocol state, and so on).
260 EHCI was designed with USB 2.0; its design has features that
261 resemble OHCI (hardware does much more work) as well as
262 UHCI (some parts of ISO support, TD list processing).
265 <para>There are host controllers other than the "big three",
266 although most PCI based controllers (and a few non-PCI based
267 ones) use one of those interfaces.
268 Not all host controllers use DMA; some use PIO, and there
272 <para>The same basic APIs are available to drivers for all
274 For historical reasons they are in two layers:
275 <structname>struct usb_bus</structname> is a rather thin
276 layer that became available in the 2.2 kernels, while
277 <structname>struct usb_hcd</structname> is a more featureful
278 layer (available in later 2.4 kernels and in 2.5) that
279 lets HCDs share common code, to shrink driver size
280 and significantly reduce hcd-specific behaviors.
283 !Edrivers/usb/core/hcd.c
284 !Edrivers/usb/core/hcd-pci.c
285 !Idrivers/usb/core/buffer.c
289 <title>The USB Filesystem (usbfs)</title>
291 <para>This chapter presents the Linux <emphasis>usbfs</emphasis>.
292 You may prefer to avoid writing new kernel code for your
293 USB driver; that's the problem that usbfs set out to solve.
294 User mode device drivers are usually packaged as applications
295 or libraries, and may use usbfs through some programming library
296 that wraps it. Such libraries include
297 <ulink url="http://libusb.sourceforge.net">libusb</ulink>
299 <ulink url="http://jUSB.sourceforge.net">jUSB</ulink> for Java.
302 <note><title>Unfinished</title>
303 <para>This particular documentation is incomplete,
304 especially with respect to the asynchronous mode.
305 As of kernel 2.5.66 the code and this (new) documentation
306 need to be cross-reviewed.
310 <para>Configure usbfs into Linux kernels by enabling the
311 <emphasis>USB filesystem</emphasis> option (CONFIG_USB_DEVICEFS),
312 and you get basic support for user mode USB device drivers.
313 Until relatively recently it was often (confusingly) called
314 <emphasis>usbdevfs</emphasis> although it wasn't solving what
315 <emphasis>devfs</emphasis> was.
316 Every USB device will appear in usbfs, regardless of whether or
317 not it has a kernel driver; but only devices with kernel drivers
322 <title>What files are in "usbfs"?</title>
324 <para>Conventionally mounted at
325 <filename>/proc/bus/usb</filename>, usbfs
328 <listitem><para><filename>/proc/bus/usb/devices</filename>
330 showing each of the USB devices on known to the kernel,
331 and their configuration descriptors.
332 You can also poll() this to learn about new devices.
334 <listitem><para><filename>/proc/bus/usb/BBB/DDD</filename>
336 exposing the each device's configuration descriptors, and
337 supporting a series of ioctls for making device requests,
338 including I/O to devices. (Purely for access by programs.)
343 <para> Each bus is given a number (BBB) based on when it was
344 enumerated; within each bus, each device is given a similar
346 Those BBB/DDD paths are not "stable" identifiers;
347 expect them to change even if you always leave the devices
348 plugged in to the same hub port.
349 <emphasis>Don't even think of saving these in application
350 configuration files.</emphasis>
351 Stable identifiers are available, for user mode applications
352 that want to use them. HID and networking devices expose
353 these stable IDs, so that for example you can be sure that
354 you told the right UPS to power down its second server.
355 "usbfs" doesn't (yet) expose those IDs.
361 <title>Mounting and Access Control</title>
363 <para>There are a number of mount options for usbfs, which will
364 be of most interest to you if you need to override the default
365 access control policy.
366 That policy is that only root may read or write device files
367 (<filename>/proc/bus/BBB/DDD</filename>) although anyone may read
368 the <filename>devices</filename>
369 or <filename>drivers</filename> files.
370 I/O requests to the device also need the CAP_SYS_RAWIO capability,
373 <para>The significance of that is that by default, all user mode
374 device drivers need super-user privileges.
375 You can change modes or ownership in a driver setup
376 when the device hotplugs, or maye just start the
377 driver right then, as a privileged server (or some activity
379 That's the most secure approach for multi-user systems,
380 but for single user systems ("trusted" by that user)
381 it's more convenient just to grant everyone all access
382 (using the <emphasis>devmode=0666</emphasis> option)
383 so the driver can start whenever it's needed.
386 <para>The mount options for usbfs, usable in /etc/fstab or
387 in command line invocations of <emphasis>mount</emphasis>, are:
391 <term><emphasis>busgid</emphasis>=NNNNN</term>
392 <listitem><para>Controls the GID used for the
394 directories. (Default: 0)</para></listitem></varlistentry>
395 <varlistentry><term><emphasis>busmode</emphasis>=MMM</term>
396 <listitem><para>Controls the file mode used for the
398 directories. (Default: 0555)
399 </para></listitem></varlistentry>
400 <varlistentry><term><emphasis>busuid</emphasis>=NNNNN</term>
401 <listitem><para>Controls the UID used for the
403 directories. (Default: 0)</para></listitem></varlistentry>
405 <varlistentry><term><emphasis>devgid</emphasis>=NNNNN</term>
406 <listitem><para>Controls the GID used for the
407 /proc/bus/usb/BBB/DDD
408 files. (Default: 0)</para></listitem></varlistentry>
409 <varlistentry><term><emphasis>devmode</emphasis>=MMM</term>
410 <listitem><para>Controls the file mode used for the
411 /proc/bus/usb/BBB/DDD
412 files. (Default: 0644)</para></listitem></varlistentry>
413 <varlistentry><term><emphasis>devuid</emphasis>=NNNNN</term>
414 <listitem><para>Controls the UID used for the
415 /proc/bus/usb/BBB/DDD
416 files. (Default: 0)</para></listitem></varlistentry>
418 <varlistentry><term><emphasis>listgid</emphasis>=NNNNN</term>
419 <listitem><para>Controls the GID used for the
420 /proc/bus/usb/devices and drivers files.
421 (Default: 0)</para></listitem></varlistentry>
422 <varlistentry><term><emphasis>listmode</emphasis>=MMM</term>
423 <listitem><para>Controls the file mode used for the
424 /proc/bus/usb/devices and drivers files.
425 (Default: 0444)</para></listitem></varlistentry>
426 <varlistentry><term><emphasis>listuid</emphasis>=NNNNN</term>
427 <listitem><para>Controls the UID used for the
428 /proc/bus/usb/devices and drivers files.
429 (Default: 0)</para></listitem></varlistentry>
434 <para>Note that many Linux distributions hard-wire the mount options
435 for usbfs in their init scripts, such as
436 <filename>/etc/rc.d/rc.sysinit</filename>,
437 rather than making it easy to set this per-system
438 policy in <filename>/etc/fstab</filename>.
444 <title>/proc/bus/usb/devices</title>
446 <para>This file is handy for status viewing tools in user
447 mode, which can scan the text format and ignore most of it.
448 More detailed device status (including class and vendor
449 status) is available from device-specific files.
450 For information about the current format of this file,
452 <filename>Documentation/usb/proc_usb_info.txt</filename>
453 file in your Linux kernel sources.
456 <para>Otherwise the main use for this file from programs
457 is to poll() it to get notifications of usb devices
458 as they're plugged or unplugged.
459 To see what changed, you'd need to read the file and
460 compare "before" and "after" contents, scan the filesystem,
461 or see its hotplug event.
467 <title>/proc/bus/usb/BBB/DDD</title>
469 <para>Use these files in one of these basic ways:
472 <para><emphasis>They can be read,</emphasis>
473 producing first the device descriptor
474 (18 bytes) and then the descriptors for the current configuration.
475 See the USB 2.0 spec for details about those binary data formats.
476 You'll need to convert most multibyte values from little endian
477 format to your native host byte order, although a few of the
478 fields in the device descriptor (both of the BCD-encoded fields,
479 and the vendor and product IDs) will be byteswapped for you.
480 Note that configuration descriptors include descriptors for
481 interfaces, altsettings, endpoints, and maybe additional
485 <para><emphasis>Perform USB operations</emphasis> using
486 <emphasis>ioctl()</emphasis> requests to make endpoint I/O
487 requests (synchronously or asynchronously) or manage
489 These requests need the CAP_SYS_RAWIO capability,
490 as well as filesystem access permissions.
491 Only one ioctl request can be made on one of these
492 device files at a time.
493 This means that if you are synchronously reading an endpoint
494 from one thread, you won't be able to write to a different
495 endpoint from another thread until the read completes.
496 This works for <emphasis>half duplex</emphasis> protocols,
497 but otherwise you'd use asynchronous i/o requests.
504 <title>Life Cycle of User Mode Drivers</title>
506 <para>Such a driver first needs to find a device file
507 for a device it knows how to handle.
508 Maybe it was told about it because a
509 <filename>/sbin/hotplug</filename> event handling agent
510 chose that driver to handle the new device.
511 Or maybe it's an application that scans all the
512 /proc/bus/usb device files, and ignores most devices.
513 In either case, it should <function>read()</function> all
514 the descriptors from the device file,
515 and check them against what it knows how to handle.
516 It might just reject everything except a particular
517 vendor and product ID, or need a more complex policy.
520 <para>Never assume there will only be one such device
521 on the system at a time!
522 If your code can't handle more than one device at
523 a time, at least detect when there's more than one, and
524 have your users choose which device to use.
527 <para>Once your user mode driver knows what device to use,
528 it interacts with it in either of two styles.
529 The simple style is to make only control requests; some
530 devices don't need more complex interactions than those.
531 (An example might be software using vendor-specific control
532 requests for some initialization or configuration tasks,
533 with a kernel driver for the rest.)
536 <para>More likely, you need a more complex style driver:
537 one using non-control endpoints, reading or writing data
538 and claiming exclusive use of an interface.
539 <emphasis>Bulk</emphasis> transfers are easiest to use,
540 but only their sibling <emphasis>interrupt</emphasis> transfers
541 work with low speed devices.
542 Both interrupt and <emphasis>isochronous</emphasis> transfers
543 offer service guarantees because their bandwidth is reserved.
544 Such "periodic" transfers are awkward to use through usbfs,
545 unless you're using the asynchronous calls. However, interrupt
546 transfers can also be used in a synchronous "one shot" style.
549 <para>Your user-mode driver should never need to worry
550 about cleaning up request state when the device is
551 disconnected, although it should close its open file
552 descriptors as soon as it starts seeing the ENODEV
558 <sect1><title>The ioctl() Requests</title>
560 <para>To use these ioctls, you need to include the following
561 headers in your userspace program:
562 <programlisting>#include <linux/usb.h>
563 #include <linux/usbdevice_fs.h>
564 #include <asm/byteorder.h></programlisting>
565 The standard USB device model requests, from "Chapter 9" of
566 the USB 2.0 specification, are automatically included from
567 the <filename><linux/usb_ch9.h></filename> header.
570 <para>Unless noted otherwise, the ioctl requests
572 update the modification time on the usbfs file to which
573 they are applied (unless they fail).
574 A return of zero indicates success; otherwise, a
575 standard USB error code is returned. (These are
577 <filename>Documentation/usb/error-codes.txt</filename>
578 in your kernel sources.)
581 <para>Each of these files multiplexes access to several
582 I/O streams, one per endpoint.
583 Each device has one control endpoint (endpoint zero)
584 which supports a limited RPC style RPC access.
585 Devices are configured
586 by khubd (in the kernel) setting a device-wide
587 <emphasis>configuration</emphasis> that affects things
588 like power consumption and basic functionality.
589 The endpoints are part of USB <emphasis>interfaces</emphasis>,
590 which may have <emphasis>altsettings</emphasis>
591 affecting things like which endpoints are available.
592 Many devices only have a single configuration and interface,
593 so drivers for them will ignore configurations and altsettings.
598 <title>Management/Status Requests</title>
600 <para>A number of usbfs requests don't deal very directly
602 They mostly relate to device management and status.
603 These are all synchronous requests.
608 <varlistentry><term>USBDEVFS_CLAIMINTERFACE</term>
609 <listitem><para>This is used to force usbfs to
610 claim a specific interface,
611 which has not previously been claimed by usbfs or any other
613 The ioctl parameter is an integer holding the number of
614 the interface (bInterfaceNumber from descriptor).
616 Note that if your driver doesn't claim an interface
617 before trying to use one of its endpoints, and no
618 other driver has bound to it, then the interface is
619 automatically claimed by usbfs.
621 This claim will be released by a RELEASEINTERFACE ioctl,
622 or by closing the file descriptor.
623 File modification time is not updated by this request.
624 </para></listitem></varlistentry>
626 <varlistentry><term>USBDEVFS_CONNECTINFO</term>
627 <listitem><para>Says whether the device is lowspeed.
628 The ioctl parameter points to a structure like this:
629 <programlisting>struct usbdevfs_connectinfo {
633 File modification time is not updated by this request.
635 <emphasis>You can't tell whether a "not slow"
636 device is connected at high speed (480 MBit/sec)
637 or just full speed (12 MBit/sec).</emphasis>
638 You should know the devnum value already,
639 it's the DDD value of the device file name.
640 </para></listitem></varlistentry>
642 <varlistentry><term>USBDEVFS_GETDRIVER</term>
643 <listitem><para>Returns the name of the kernel driver
644 bound to a given interface (a string). Parameter
645 is a pointer to this structure, which is modified:
646 <programlisting>struct usbdevfs_getdriver {
647 unsigned int interface;
648 char driver[USBDEVFS_MAXDRIVERNAME + 1];
650 File modification time is not updated by this request.
651 </para></listitem></varlistentry>
653 <varlistentry><term>USBDEVFS_IOCTL</term>
654 <listitem><para>Passes a request from userspace through
655 to a kernel driver that has an ioctl entry in the
656 <emphasis>struct usb_driver</emphasis> it registered.
657 <programlisting>struct usbdevfs_ioctl {
663 /* user mode call looks like this.
664 * 'request' becomes the driver->ioctl() 'code' parameter.
665 * the size of 'param' is encoded in 'request', and that data
666 * is copied to or from the driver->ioctl() 'buf' parameter.
669 usbdev_ioctl (int fd, int ifno, unsigned request, void *param)
671 struct usbdevfs_ioctl wrapper;
674 wrapper.ioctl_code = request;
675 wrapper.data = param;
677 return ioctl (fd, USBDEVFS_IOCTL, &wrapper);
679 File modification time is not updated by this request.
681 This request lets kernel drivers talk to user mode code
682 through filesystem operations even when they don't create
683 a charactor or block special device.
684 It's also been used to do things like ask devices what
685 device special file should be used.
686 Two pre-defined ioctls are used
687 to disconnect and reconnect kernel drivers, so
688 that user mode code can completely manage binding
689 and configuration of devices.
690 </para></listitem></varlistentry>
692 <varlistentry><term>USBDEVFS_RELEASEINTERFACE</term>
693 <listitem><para>This is used to release the claim usbfs
694 made on interface, either implicitly or because of a
695 USBDEVFS_CLAIMINTERFACE call, before the file
696 descriptor is closed.
697 The ioctl parameter is an integer holding the number of
698 the interface (bInterfaceNumber from descriptor);
699 File modification time is not updated by this request.
700 </para><warning><para>
701 <emphasis>No security check is made to ensure
702 that the task which made the claim is the one
703 which is releasing it.
704 This means that user mode driver may interfere
705 other ones. </emphasis>
706 </para></warning></listitem></varlistentry>
708 <varlistentry><term>USBDEVFS_RESETEP</term>
709 <listitem><para>Resets the data toggle value for an endpoint
710 (bulk or interrupt) to DATA0.
711 The ioctl parameter is an integer endpoint number
712 (1 to 15, as identified in the endpoint descriptor),
713 with USB_DIR_IN added if the device's endpoint sends
715 </para><warning><para>
716 <emphasis>Avoid using this request.
717 It should probably be removed.</emphasis>
718 Using it typically means the device and driver will lose
719 toggle synchronization. If you really lost synchronization,
720 you likely need to completely handshake with the device,
721 using a request like CLEAR_HALT
723 </para></warning></listitem></varlistentry>
730 <title>Synchronous I/O Support</title>
732 <para>Synchronous requests involve the kernel blocking
733 until until the user mode request completes, either by
734 finishing successfully or by reporting an error.
735 In most cases this is the simplest way to use usbfs,
736 although as noted above it does prevent performing I/O
737 to more than one endpoint at a time.
742 <varlistentry><term>USBDEVFS_BULK</term>
743 <listitem><para>Issues a bulk read or write request to the
745 The ioctl parameter is a pointer to this structure:
746 <programlisting>struct usbdevfs_bulktransfer {
749 unsigned int timeout; /* in milliseconds */
752 </para><para>The "ep" value identifies a
753 bulk endpoint number (1 to 15, as identified in an endpoint
755 masked with USB_DIR_IN when referring to an endpoint which
756 sends data to the host from the device.
757 The length of the data buffer is identified by "len";
758 Recent kernels support requests up to about 128KBytes.
759 <emphasis>FIXME say how read length is returned,
760 and how short reads are handled.</emphasis>.
761 </para></listitem></varlistentry>
763 <varlistentry><term>USBDEVFS_CLEAR_HALT</term>
764 <listitem><para>Clears endpoint halt (stall) and
765 resets the endpoint toggle. This is only
766 meaningful for bulk or interrupt endpoints.
767 The ioctl parameter is an integer endpoint number
768 (1 to 15, as identified in an endpoint descriptor),
769 masked with USB_DIR_IN when referring to an endpoint which
770 sends data to the host from the device.
772 Use this on bulk or interrupt endpoints which have
773 stalled, returning <emphasis>-EPIPE</emphasis> status
774 to a data transfer request.
775 Do not issue the control request directly, since
776 that could invalidate the host's record of the
778 </para></listitem></varlistentry>
780 <varlistentry><term>USBDEVFS_CONTROL</term>
781 <listitem><para>Issues a control request to the device.
782 The ioctl parameter points to a structure like this:
783 <programlisting>struct usbdevfs_ctrltransfer {
789 __u32 timeout; /* in milliseconds */
793 The first eight bytes of this structure are the contents
794 of the SETUP packet to be sent to the device; see the
795 USB 2.0 specification for details.
796 The bRequestType value is composed by combining a
797 USB_TYPE_* value, a USB_DIR_* value, and a
798 USB_RECIP_* value (from
799 <emphasis><linux/usb.h></emphasis>).
800 If wLength is nonzero, it describes the length of the data
801 buffer, which is either written to the device
802 (USB_DIR_OUT) or read from the device (USB_DIR_IN).
804 At this writing, you can't transfer more than 4 KBytes
805 of data to or from a device; usbfs has a limit, and
806 some host controller drivers have a limit.
807 (That's not usually a problem.)
808 <emphasis>Also</emphasis> there's no way to say it's
809 not OK to get a short read back from the device.
810 </para></listitem></varlistentry>
812 <varlistentry><term>USBDEVFS_RESET</term>
813 <listitem><para>Does a USB level device reset.
814 The ioctl parameter is ignored.
815 After the reset, this rebinds all device interfaces.
816 File modification time is not updated by this request.
817 </para><warning><para>
818 <emphasis>Avoid using this call</emphasis>
819 until some usbcore bugs get fixed,
820 since it does not fully synchronize device, interface,
821 and driver (not just usbfs) state.
822 </para></warning></listitem></varlistentry>
824 <varlistentry><term>USBDEVFS_SETINTERFACE</term>
825 <listitem><para>Sets the alternate setting for an
826 interface. The ioctl parameter is a pointer to a
828 <programlisting>struct usbdevfs_setinterface {
829 unsigned int interface;
830 unsigned int altsetting;
832 File modification time is not updated by this request.
834 Those struct members are from some interface descriptor
835 applying to the current configuration.
836 The interface number is the bInterfaceNumber value, and
837 the altsetting number is the bAlternateSetting value.
838 (This resets each endpoint in the interface.)
839 </para></listitem></varlistentry>
841 <varlistentry><term>USBDEVFS_SETCONFIGURATION</term>
842 <listitem><para>Issues the
843 <function>usb_set_configuration</function> call
845 The parameter is an integer holding the number of
846 a configuration (bConfigurationValue from descriptor).
847 File modification time is not updated by this request.
848 </para><warning><para>
849 <emphasis>Avoid using this call</emphasis>
850 until some usbcore bugs get fixed,
851 since it does not fully synchronize device, interface,
852 and driver (not just usbfs) state.
853 </para></warning></listitem></varlistentry>
859 <title>Asynchronous I/O Support</title>
861 <para>As mentioned above, there are situations where it may be
862 important to initiate concurrent operations from user mode code.
863 This is particularly important for periodic transfers
864 (interrupt and isochronous), but it can be used for other
865 kinds of USB requests too.
866 In such cases, the asynchronous requests described here
867 are essential. Rather than submitting one request and having
868 the kernel block until it completes, the blocking is separate.
871 <para>These requests are packaged into a structure that
872 resembles the URB used by kernel device drivers.
873 (No POSIX Async I/O support here, sorry.)
874 It identifies the endpoint type (USBDEVFS_URB_TYPE_*),
875 endpoint (number, masked with USB_DIR_IN as appropriate),
876 buffer and length, and a user "context" value serving to
877 uniquely identify each request.
878 (It's usually a pointer to per-request data.)
879 Flags can modify requests (not as many as supported for
883 <para>Each request can specify a realtime signal number
884 (between SIGRTMIN and SIGRTMAX, inclusive) to request a
885 signal be sent when the request completes.
888 <para>When usbfs returns these urbs, the status value
889 is updated, and the buffer may have been modified.
890 Except for isochronous transfers, the actual_length is
891 updated to say how many bytes were transferred; if the
892 USBDEVFS_URB_DISABLE_SPD flag is set
893 ("short packets are not OK"), if fewer bytes were read
894 than were requested then you get an error report.
897 <programlisting>struct usbdevfs_iso_packet_desc {
899 unsigned int actual_length;
903 struct usbdevfs_urb {
905 unsigned char endpoint;
912 int number_of_packets;
916 struct usbdevfs_iso_packet_desc iso_frame_desc[];
919 <para> For these asynchronous requests, the file modification
920 time reflects when the request was initiated.
921 This contrasts with their use with the synchronous requests,
922 where it reflects when requests complete.
927 <varlistentry><term>USBDEVFS_DISCARDURB</term>
929 <emphasis>TBS</emphasis>
930 File modification time is not updated by this request.
932 </para></listitem></varlistentry>
934 <varlistentry><term>USBDEVFS_DISCSIGNAL</term>
936 <emphasis>TBS</emphasis>
937 File modification time is not updated by this request.
939 </para></listitem></varlistentry>
941 <varlistentry><term>USBDEVFS_REAPURB</term>
943 <emphasis>TBS</emphasis>
944 File modification time is not updated by this request.
946 </para></listitem></varlistentry>
948 <varlistentry><term>USBDEVFS_REAPURBNDELAY</term>
950 <emphasis>TBS</emphasis>
951 File modification time is not updated by this request.
953 </para></listitem></varlistentry>
955 <varlistentry><term>USBDEVFS_SUBMITURB</term>
957 <emphasis>TBS</emphasis>
959 </para></listitem></varlistentry>
969 <!-- vim:syntax=sgml:sw=4