8a28f76b935958028d84c5ec8f167e02a16299a0
[linux-2.6.git] / Documentation / DocBook / usb.tmpl
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" []>
4
5 <book id="Linux-USB-API">
6  <bookinfo>
7   <title>The Linux-USB Host Side API</title>
8   
9   <legalnotice>
10    <para>
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
15      version.
16    </para>
17       
18    <para>
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.
23    </para>
24       
25    <para>
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,
29      MA 02111-1307 USA
30    </para>
31       
32    <para>
33      For more details see the file COPYING in the source
34      distribution of Linux.
35    </para>
36   </legalnotice>
37  </bookinfo>
38
39 <toc></toc>
40
41 <chapter id="intro">
42     <title>Introduction to USB on Linux</title>
43
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".
53     </para>
54
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.
65     </para>
66
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).
73     </para>
74
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.
83     </para>
84
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.
92     </para>
93
94     </chapter>
95
96 <chapter id="host">
97     <title>USB Host-Side API Model</title>
98
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.
108     </para>
109
110     <para>The device model seen by USB drivers is relatively complex.
111     </para>
112      
113     <itemizedlist>
114
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.
120         </para></listitem>
121
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.
127         </para></listitem>
128
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>
133
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>
139         </para></listitem>
140
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.
146         </para></listitem>
147
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.
152         </para></listitem>
153
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).
158         </para></listitem>
159
160     </itemizedlist>
161
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.
166     </para>
167
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
176     consistent.
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.)
184     </para>
185
186     </chapter>
187
188 <chapter><title>USB-Standard Types</title>
189
190     <para>In <filename>&lt;linux/usb_ch9.h&gt;</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.
194     </para>
195
196 !Iinclude/linux/usb_ch9.h
197
198     </chapter>
199
200 <chapter><title>Host-Side Data Types and Macros</title>
201
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.
207     </para>
208
209
210 !Iinclude/linux/usb.h
211
212     </chapter>
213
214     <chapter><title>USB Core APIs</title>
215
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).
232     </para>
233
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.
241     </para>
242
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
249     </chapter>
250
251     <chapter><title>Host Controller APIs</title>
252
253     <para>These APIs are only for use by host controller drivers,
254     most of which implement standard register interfaces such as
255     EHCI, OHCI, or UHCI.
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).
263     </para>
264
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
269     is also a simulator.
270     </para>
271
272     <para>The same basic APIs are available to drivers for all
273     those controllers.  
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.
281     </para>
282
283 !Edrivers/usb/core/hcd.c
284 !Edrivers/usb/core/hcd-pci.c
285 !Idrivers/usb/core/buffer.c
286     </chapter>
287
288     <chapter>
289         <title>The USB Filesystem (usbfs)</title>
290
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>
298         for C/C++, and
299         <ulink url="http://jUSB.sourceforge.net">jUSB</ulink> for Java.
300         </para>
301
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.
307             </para>
308             </note>
309
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
318         show up in devfs.
319         </para>
320
321         <sect1>
322             <title>What files are in "usbfs"?</title>
323
324             <para>Conventionally mounted at
325             <filename>/proc/bus/usb</filename>, usbfs 
326             features include:
327             <itemizedlist>
328                 <listitem><para><filename>/proc/bus/usb/devices</filename>
329                     ... a text file
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.
333                     </para></listitem>
334                 <listitem><para><filename>/proc/bus/usb/BBB/DDD</filename>
335                     ... magic files
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.)
339                     </para></listitem>
340             </itemizedlist>
341             </para>
342
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
345             number (DDD).
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.
356             </para>
357
358         </sect1>
359
360         <sect1>
361             <title>Mounting and Access Control</title>
362
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,
371             </para>
372
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
378             within one).
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.
384             </para>
385
386             <para>The mount options for usbfs, usable in /etc/fstab or
387             in command line invocations of <emphasis>mount</emphasis>, are:
388
389             <variablelist>
390                 <varlistentry>
391                     <term><emphasis>busgid</emphasis>=NNNNN</term>
392                     <listitem><para>Controls the GID used for the
393                     /proc/bus/usb/BBB
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
397                     /proc/bus/usb/BBB
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
402                     /proc/bus/usb/BBB
403                     directories.  (Default: 0)</para></listitem></varlistentry>
404
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>
417
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>
430             </variablelist>
431
432             </para>
433
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>.
439             </para>
440
441         </sect1>
442
443         <sect1>
444             <title>/proc/bus/usb/devices</title>
445
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,
451             see the
452             <filename>Documentation/usb/proc_usb_info.txt</filename>
453             file in your Linux kernel sources.
454             </para>
455
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.
462             </para>
463
464         </sect1>
465
466         <sect1>
467             <title>/proc/bus/usb/BBB/DDD</title>
468
469             <para>Use these files in one of these basic ways:
470             </para>
471
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
482             class descriptors.
483             </para>
484
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
488             the device.
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. 
498             </para>
499
500             </sect1>
501
502
503         <sect1>
504             <title>Life Cycle of User Mode Drivers</title>
505
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.
518             </para>
519
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.
525             </para>
526
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.)
534             </para>
535
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.
547             </para>
548
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
553             errors.
554             </para>
555
556             </sect1>
557
558         <sect1><title>The ioctl() Requests</title>
559
560             <para>To use these ioctls, you need to include the following
561             headers in your userspace program:
562 <programlisting>#include &lt;linux/usb.h&gt;
563 #include &lt;linux/usbdevice_fs.h&gt;
564 #include &lt;asm/byteorder.h&gt;</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>&lt;linux/usb_ch9.h&gt;</filename> header.
568             </para>
569
570             <para>Unless noted otherwise, the ioctl requests
571             described here will
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
576             documented in
577             <filename>Documentation/usb/error-codes.txt</filename>
578             in your kernel sources.)
579             </para>
580
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.
594             </para>
595
596
597             <sect2>
598                 <title>Management/Status Requests</title>
599
600                 <para>A number of usbfs requests don't deal very directly
601                 with device I/O.
602                 They mostly relate to device management and status.
603                 These are all synchronous requests.
604                 </para>
605
606                 <variablelist>
607
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
612                     kernel driver.
613                     The ioctl parameter is an integer holding the number of
614                     the interface (bInterfaceNumber from descriptor).
615                     </para><para>
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.
620                     </para><para>
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>
625
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 {
630         unsigned int   devnum;
631         unsigned char  slow;
632 }; </programlisting>
633                     File modification time is not updated by this request.
634                     </para><para>
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>
641
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];
649 };</programlisting>
650                     File modification time is not updated by this request.
651                     </para></listitem></varlistentry>
652
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 {
658         int     ifno;
659         int     ioctl_code;
660         void    *data;
661 };
662
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.
667  */
668 static int
669 usbdev_ioctl (int fd, int ifno, unsigned request, void *param)
670 {
671         struct usbdevfs_ioctl   wrapper;
672
673         wrapper.ifno = ifno;
674         wrapper.ioctl_code = request;
675         wrapper.data = param;
676
677         return ioctl (fd, USBDEVFS_IOCTL, &amp;wrapper);
678 } </programlisting>
679                     File modification time is not updated by this request.
680                     </para><para>
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>
691
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>
707
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
714                     data to the host.
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
722                     or SET_INTERFACE.
723                     </para></warning></listitem></varlistentry>
724
725                 </variablelist>
726
727                 </sect2>
728
729             <sect2>
730                 <title>Synchronous I/O Support</title>
731
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.
738                 </para>
739
740                 <variablelist>
741
742                 <varlistentry><term>USBDEVFS_BULK</term>
743                     <listitem><para>Issues a bulk read or write request to the
744                     device.
745                     The ioctl parameter is a pointer to this structure:
746 <programlisting>struct usbdevfs_bulktransfer {
747         unsigned int  ep;
748         unsigned int  len;
749         unsigned int  timeout; /* in milliseconds */
750         void          *data;
751 };</programlisting>
752                     </para><para>The "ep" value identifies a
753                     bulk endpoint number (1 to 15, as identified in an endpoint
754                     descriptor),
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>
762
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.
771                     </para><para>
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
777                     data toggle.
778                     </para></listitem></varlistentry>
779
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 {
784         __u8   bRequestType;
785         __u8   bRequest;
786         __u16  wValue;
787         __u16  wIndex;
788         __u16  wLength;
789         __u32  timeout;  /* in milliseconds */
790         void   *data;
791 };</programlisting>
792                     </para><para>
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>&lt;linux/usb.h&gt;</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).
803                     </para><para>
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>
811
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>
823             
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
827                     structure like this:
828 <programlisting>struct usbdevfs_setinterface {
829         unsigned int  interface;
830         unsigned int  altsetting;
831 }; </programlisting>
832                     File modification time is not updated by this request.
833                     </para><para>
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>
840
841                 <varlistentry><term>USBDEVFS_SETCONFIGURATION</term>
842                     <listitem><para>Issues the
843                     <function>usb_set_configuration</function> call
844                     for the device.
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>
854
855                 </variablelist>
856             </sect2>
857
858             <sect2>
859                 <title>Asynchronous I/O Support</title>
860
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.
869                 </para>
870
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
880                 kernel drivers).
881                 </para>
882
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.
886                 </para>
887
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.
895                 </para>
896
897 <programlisting>struct usbdevfs_iso_packet_desc {
898         unsigned int                     length;
899         unsigned int                     actual_length;
900         unsigned int                     status;
901 };
902
903 struct usbdevfs_urb {
904         unsigned char                    type;
905         unsigned char                    endpoint;
906         int                              status;
907         unsigned int                     flags;
908         void                             *buffer;
909         int                              buffer_length;
910         int                              actual_length;
911         int                              start_frame;
912         int                              number_of_packets;
913         int                              error_count;
914         unsigned int                     signr;
915         void                             *usercontext;
916         struct usbdevfs_iso_packet_desc  iso_frame_desc[];
917 };</programlisting>
918
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.
923                 </para>
924
925                 <variablelist>
926
927                 <varlistentry><term>USBDEVFS_DISCARDURB</term>
928                     <listitem><para>
929                     <emphasis>TBS</emphasis>
930                     File modification time is not updated by this request.
931                     </para><para>
932                     </para></listitem></varlistentry>
933
934                 <varlistentry><term>USBDEVFS_DISCSIGNAL</term>
935                     <listitem><para>
936                     <emphasis>TBS</emphasis>
937                     File modification time is not updated by this request.
938                     </para><para>
939                     </para></listitem></varlistentry>
940
941                 <varlistentry><term>USBDEVFS_REAPURB</term>
942                     <listitem><para>
943                     <emphasis>TBS</emphasis>
944                     File modification time is not updated by this request.
945                     </para><para>
946                     </para></listitem></varlistentry>
947
948                 <varlistentry><term>USBDEVFS_REAPURBNDELAY</term>
949                     <listitem><para>
950                     <emphasis>TBS</emphasis>
951                     File modification time is not updated by this request.
952                     </para><para>
953                     </para></listitem></varlistentry>
954
955                 <varlistentry><term>USBDEVFS_SUBMITURB</term>
956                     <listitem><para>
957                     <emphasis>TBS</emphasis>
958                     </para><para>
959                     </para></listitem></varlistentry>
960
961                 </variablelist>
962             </sect2>
963
964         </sect1>
965
966     </chapter>
967
968 </book>
969 <!-- vim:syntax=sgml:sw=4
970 -->