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