[PATCH] kernel-doc for kernel/dma.c
[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>This file, in combination with the poll() system call, can
457             also be used to detect when devices are added or removed:
458 <programlisting>int fd;
459 struct pollfd pfd;
460
461 fd = open("/proc/bus/usb/devices", O_RDONLY);
462 pfd = { fd, POLLIN, 0 };
463 for (;;) {
464         /* The first time through, this call will return immediately. */
465         poll(&amp;pfd, 1, -1);
466
467         /* To see what's changed, compare the file's previous and current
468            contents or scan the filesystem.  (Scanning is more precise.) */
469 }</programlisting>
470             Note that this behavior is intended to be used for informational
471             and debug purposes.  It would be more appropriate to use programs
472             such as udev or HAL to initialize a device or start a user-mode
473             helper program, for instance.
474             </para>
475         </sect1>
476
477         <sect1>
478             <title>/proc/bus/usb/BBB/DDD</title>
479
480             <para>Use these files in one of these basic ways:
481             </para>
482
483             <para><emphasis>They can be read,</emphasis>
484             producing first the device descriptor
485             (18 bytes) and then the descriptors for the current configuration.
486             See the USB 2.0 spec for details about those binary data formats.
487             You'll need to convert most multibyte values from little endian
488             format to your native host byte order, although a few of the
489             fields in the device descriptor (both of the BCD-encoded fields,
490             and the vendor and product IDs) will be byteswapped for you.
491             Note that configuration descriptors include descriptors for
492             interfaces, altsettings, endpoints, and maybe additional
493             class descriptors.
494             </para>
495
496             <para><emphasis>Perform USB operations</emphasis> using 
497             <emphasis>ioctl()</emphasis> requests to make endpoint I/O
498             requests (synchronously or asynchronously) or manage
499             the device.
500             These requests need the CAP_SYS_RAWIO capability,
501             as well as filesystem access permissions.
502             Only one ioctl request can be made on one of these
503             device files at a time.
504             This means that if you are synchronously reading an endpoint
505             from one thread, you won't be able to write to a different
506             endpoint from another thread until the read completes.
507             This works for <emphasis>half duplex</emphasis> protocols,
508             but otherwise you'd use asynchronous i/o requests. 
509             </para>
510
511             </sect1>
512
513
514         <sect1>
515             <title>Life Cycle of User Mode Drivers</title>
516
517             <para>Such a driver first needs to find a device file
518             for a device it knows how to handle.
519             Maybe it was told about it because a
520             <filename>/sbin/hotplug</filename> event handling agent
521             chose that driver to handle the new device.
522             Or maybe it's an application that scans all the
523             /proc/bus/usb device files, and ignores most devices.
524             In either case, it should <function>read()</function> all
525             the descriptors from the device file,
526             and check them against what it knows how to handle.
527             It might just reject everything except a particular
528             vendor and product ID, or need a more complex policy.
529             </para>
530
531             <para>Never assume there will only be one such device
532             on the system at a time!
533             If your code can't handle more than one device at
534             a time, at least detect when there's more than one, and
535             have your users choose which device to use.
536             </para>
537
538             <para>Once your user mode driver knows what device to use,
539             it interacts with it in either of two styles.
540             The simple style is to make only control requests; some
541             devices don't need more complex interactions than those.
542             (An example might be software using vendor-specific control
543             requests for some initialization or configuration tasks,
544             with a kernel driver for the rest.)
545             </para>
546
547             <para>More likely, you need a more complex style driver:
548             one using non-control endpoints, reading or writing data
549             and claiming exclusive use of an interface.
550             <emphasis>Bulk</emphasis> transfers are easiest to use,
551             but only their sibling <emphasis>interrupt</emphasis> transfers 
552             work with low speed devices.
553             Both interrupt and <emphasis>isochronous</emphasis> transfers
554             offer service guarantees because their bandwidth is reserved.
555             Such "periodic" transfers are awkward to use through usbfs,
556             unless you're using the asynchronous calls.  However, interrupt
557             transfers can also be used in a synchronous "one shot" style.
558             </para>
559
560             <para>Your user-mode driver should never need to worry
561             about cleaning up request state when the device is
562             disconnected, although it should close its open file
563             descriptors as soon as it starts seeing the ENODEV
564             errors.
565             </para>
566
567             </sect1>
568
569         <sect1><title>The ioctl() Requests</title>
570
571             <para>To use these ioctls, you need to include the following
572             headers in your userspace program:
573 <programlisting>#include &lt;linux/usb.h&gt;
574 #include &lt;linux/usbdevice_fs.h&gt;
575 #include &lt;asm/byteorder.h&gt;</programlisting>
576             The standard USB device model requests, from "Chapter 9" of
577             the USB 2.0 specification, are automatically included from
578             the <filename>&lt;linux/usb_ch9.h&gt;</filename> header.
579             </para>
580
581             <para>Unless noted otherwise, the ioctl requests
582             described here will
583             update the modification time on the usbfs file to which
584             they are applied (unless they fail).
585             A return of zero indicates success; otherwise, a
586             standard USB error code is returned.  (These are
587             documented in
588             <filename>Documentation/usb/error-codes.txt</filename>
589             in your kernel sources.)
590             </para>
591
592             <para>Each of these files multiplexes access to several
593             I/O streams, one per endpoint.
594             Each device has one control endpoint (endpoint zero)
595             which supports a limited RPC style RPC access.
596             Devices are configured
597             by khubd (in the kernel) setting a device-wide
598             <emphasis>configuration</emphasis> that affects things
599             like power consumption and basic functionality.
600             The endpoints are part of USB <emphasis>interfaces</emphasis>,
601             which may have <emphasis>altsettings</emphasis>
602             affecting things like which endpoints are available.
603             Many devices only have a single configuration and interface,
604             so drivers for them will ignore configurations and altsettings.
605             </para>
606
607
608             <sect2>
609                 <title>Management/Status Requests</title>
610
611                 <para>A number of usbfs requests don't deal very directly
612                 with device I/O.
613                 They mostly relate to device management and status.
614                 These are all synchronous requests.
615                 </para>
616
617                 <variablelist>
618
619                 <varlistentry><term>USBDEVFS_CLAIMINTERFACE</term>
620                     <listitem><para>This is used to force usbfs to
621                     claim a specific interface,
622                     which has not previously been claimed by usbfs or any other
623                     kernel driver.
624                     The ioctl parameter is an integer holding the number of
625                     the interface (bInterfaceNumber from descriptor).
626                     </para><para>
627                     Note that if your driver doesn't claim an interface
628                     before trying to use one of its endpoints, and no
629                     other driver has bound to it, then the interface is
630                     automatically claimed by usbfs.
631                     </para><para>
632                     This claim will be released by a RELEASEINTERFACE ioctl,
633                     or by closing the file descriptor.
634                     File modification time is not updated by this request.
635                     </para></listitem></varlistentry>
636
637                 <varlistentry><term>USBDEVFS_CONNECTINFO</term>
638                     <listitem><para>Says whether the device is lowspeed.
639                     The ioctl parameter points to a structure like this:
640 <programlisting>struct usbdevfs_connectinfo {
641         unsigned int   devnum;
642         unsigned char  slow;
643 }; </programlisting>
644                     File modification time is not updated by this request.
645                     </para><para>
646                     <emphasis>You can't tell whether a "not slow"
647                     device is connected at high speed (480 MBit/sec)
648                     or just full speed (12 MBit/sec).</emphasis>
649                     You should know the devnum value already,
650                     it's the DDD value of the device file name.
651                     </para></listitem></varlistentry>
652
653                 <varlistentry><term>USBDEVFS_GETDRIVER</term>
654                     <listitem><para>Returns the name of the kernel driver
655                     bound to a given interface (a string).  Parameter
656                     is a pointer to this structure, which is modified:
657 <programlisting>struct usbdevfs_getdriver {
658         unsigned int  interface;
659         char          driver[USBDEVFS_MAXDRIVERNAME + 1];
660 };</programlisting>
661                     File modification time is not updated by this request.
662                     </para></listitem></varlistentry>
663
664                 <varlistentry><term>USBDEVFS_IOCTL</term>
665                     <listitem><para>Passes a request from userspace through
666                     to a kernel driver that has an ioctl entry in the
667                     <emphasis>struct usb_driver</emphasis> it registered.
668 <programlisting>struct usbdevfs_ioctl {
669         int     ifno;
670         int     ioctl_code;
671         void    *data;
672 };
673
674 /* user mode call looks like this.
675  * 'request' becomes the driver->ioctl() 'code' parameter.
676  * the size of 'param' is encoded in 'request', and that data
677  * is copied to or from the driver->ioctl() 'buf' parameter.
678  */
679 static int
680 usbdev_ioctl (int fd, int ifno, unsigned request, void *param)
681 {
682         struct usbdevfs_ioctl   wrapper;
683
684         wrapper.ifno = ifno;
685         wrapper.ioctl_code = request;
686         wrapper.data = param;
687
688         return ioctl (fd, USBDEVFS_IOCTL, &amp;wrapper);
689 } </programlisting>
690                     File modification time is not updated by this request.
691                     </para><para>
692                     This request lets kernel drivers talk to user mode code
693                     through filesystem operations even when they don't create
694                     a charactor or block special device.
695                     It's also been used to do things like ask devices what
696                     device special file should be used.
697                     Two pre-defined ioctls are used
698                     to disconnect and reconnect kernel drivers, so
699                     that user mode code can completely manage binding
700                     and configuration of devices.
701                     </para></listitem></varlistentry>
702
703                 <varlistentry><term>USBDEVFS_RELEASEINTERFACE</term>
704                     <listitem><para>This is used to release the claim usbfs
705                     made on interface, either implicitly or because of a
706                     USBDEVFS_CLAIMINTERFACE call, before the file
707                     descriptor is closed.
708                     The ioctl parameter is an integer holding the number of
709                     the interface (bInterfaceNumber from descriptor);
710                     File modification time is not updated by this request.
711                     </para><warning><para>
712                     <emphasis>No security check is made to ensure
713                     that the task which made the claim is the one
714                     which is releasing it.
715                     This means that user mode driver may interfere
716                     other ones.  </emphasis>
717                     </para></warning></listitem></varlistentry>
718
719                 <varlistentry><term>USBDEVFS_RESETEP</term>
720                     <listitem><para>Resets the data toggle value for an endpoint
721                     (bulk or interrupt) to DATA0.
722                     The ioctl parameter is an integer endpoint number
723                     (1 to 15, as identified in the endpoint descriptor),
724                     with USB_DIR_IN added if the device's endpoint sends
725                     data to the host.
726                     </para><warning><para>
727                     <emphasis>Avoid using this request.
728                     It should probably be removed.</emphasis>
729                     Using it typically means the device and driver will lose
730                     toggle synchronization.  If you really lost synchronization,
731                     you likely need to completely handshake with the device,
732                     using a request like CLEAR_HALT
733                     or SET_INTERFACE.
734                     </para></warning></listitem></varlistentry>
735
736                 </variablelist>
737
738                 </sect2>
739
740             <sect2>
741                 <title>Synchronous I/O Support</title>
742
743                 <para>Synchronous requests involve the kernel blocking
744                 until until the user mode request completes, either by
745                 finishing successfully or by reporting an error.
746                 In most cases this is the simplest way to use usbfs,
747                 although as noted above it does prevent performing I/O
748                 to more than one endpoint at a time.
749                 </para>
750
751                 <variablelist>
752
753                 <varlistentry><term>USBDEVFS_BULK</term>
754                     <listitem><para>Issues a bulk read or write request to the
755                     device.
756                     The ioctl parameter is a pointer to this structure:
757 <programlisting>struct usbdevfs_bulktransfer {
758         unsigned int  ep;
759         unsigned int  len;
760         unsigned int  timeout; /* in milliseconds */
761         void          *data;
762 };</programlisting>
763                     </para><para>The "ep" value identifies a
764                     bulk endpoint number (1 to 15, as identified in an endpoint
765                     descriptor),
766                     masked with USB_DIR_IN when referring to an endpoint which
767                     sends data to the host from the device.
768                     The length of the data buffer is identified by "len";
769                     Recent kernels support requests up to about 128KBytes.
770                     <emphasis>FIXME say how read length is returned,
771                     and how short reads are handled.</emphasis>.
772                     </para></listitem></varlistentry>
773
774                 <varlistentry><term>USBDEVFS_CLEAR_HALT</term>
775                     <listitem><para>Clears endpoint halt (stall) and
776                     resets the endpoint toggle.  This is only
777                     meaningful for bulk or interrupt endpoints.
778                     The ioctl parameter is an integer endpoint number
779                     (1 to 15, as identified in an endpoint descriptor),
780                     masked with USB_DIR_IN when referring to an endpoint which
781                     sends data to the host from the device.
782                     </para><para>
783                     Use this on bulk or interrupt endpoints which have
784                     stalled, returning <emphasis>-EPIPE</emphasis> status
785                     to a data transfer request.
786                     Do not issue the control request directly, since
787                     that could invalidate the host's record of the
788                     data toggle.
789                     </para></listitem></varlistentry>
790
791                 <varlistentry><term>USBDEVFS_CONTROL</term>
792                     <listitem><para>Issues a control request to the device.
793                     The ioctl parameter points to a structure like this:
794 <programlisting>struct usbdevfs_ctrltransfer {
795         __u8   bRequestType;
796         __u8   bRequest;
797         __u16  wValue;
798         __u16  wIndex;
799         __u16  wLength;
800         __u32  timeout;  /* in milliseconds */
801         void   *data;
802 };</programlisting>
803                     </para><para>
804                     The first eight bytes of this structure are the contents
805                     of the SETUP packet to be sent to the device; see the
806                     USB 2.0 specification for details.
807                     The bRequestType value is composed by combining a
808                     USB_TYPE_* value, a USB_DIR_* value, and a
809                     USB_RECIP_* value (from
810                     <emphasis>&lt;linux/usb.h&gt;</emphasis>).
811                     If wLength is nonzero, it describes the length of the data
812                     buffer, which is either written to the device
813                     (USB_DIR_OUT) or read from the device (USB_DIR_IN).
814                     </para><para>
815                     At this writing, you can't transfer more than 4 KBytes
816                     of data to or from a device; usbfs has a limit, and
817                     some host controller drivers have a limit.
818                     (That's not usually a problem.)
819                     <emphasis>Also</emphasis> there's no way to say it's
820                     not OK to get a short read back from the device.
821                     </para></listitem></varlistentry>
822
823                 <varlistentry><term>USBDEVFS_RESET</term>
824                     <listitem><para>Does a USB level device reset.
825                     The ioctl parameter is ignored.
826                     After the reset, this rebinds all device interfaces.
827                     File modification time is not updated by this request.
828                     </para><warning><para>
829                     <emphasis>Avoid using this call</emphasis>
830                     until some usbcore bugs get fixed,
831                     since it does not fully synchronize device, interface,
832                     and driver (not just usbfs) state.
833                     </para></warning></listitem></varlistentry>
834             
835                 <varlistentry><term>USBDEVFS_SETINTERFACE</term>
836                     <listitem><para>Sets the alternate setting for an
837                     interface.  The ioctl parameter is a pointer to a
838                     structure like this:
839 <programlisting>struct usbdevfs_setinterface {
840         unsigned int  interface;
841         unsigned int  altsetting;
842 }; </programlisting>
843                     File modification time is not updated by this request.
844                     </para><para>
845                     Those struct members are from some interface descriptor
846                     applying to the current configuration.
847                     The interface number is the bInterfaceNumber value, and
848                     the altsetting number is the bAlternateSetting value.
849                     (This resets each endpoint in the interface.)
850                     </para></listitem></varlistentry>
851
852                 <varlistentry><term>USBDEVFS_SETCONFIGURATION</term>
853                     <listitem><para>Issues the
854                     <function>usb_set_configuration</function> call
855                     for the device.
856                     The parameter is an integer holding the number of
857                     a configuration (bConfigurationValue from descriptor).
858                     File modification time is not updated by this request.
859                     </para><warning><para>
860                     <emphasis>Avoid using this call</emphasis>
861                     until some usbcore bugs get fixed,
862                     since it does not fully synchronize device, interface,
863                     and driver (not just usbfs) state.
864                     </para></warning></listitem></varlistentry>
865
866                 </variablelist>
867             </sect2>
868
869             <sect2>
870                 <title>Asynchronous I/O Support</title>
871
872                 <para>As mentioned above, there are situations where it may be
873                 important to initiate concurrent operations from user mode code.
874                 This is particularly important for periodic transfers
875                 (interrupt and isochronous), but it can be used for other
876                 kinds of USB requests too.
877                 In such cases, the asynchronous requests described here
878                 are essential.  Rather than submitting one request and having
879                 the kernel block until it completes, the blocking is separate.
880                 </para>
881
882                 <para>These requests are packaged into a structure that
883                 resembles the URB used by kernel device drivers.
884                 (No POSIX Async I/O support here, sorry.)
885                 It identifies the endpoint type (USBDEVFS_URB_TYPE_*),
886                 endpoint (number, masked with USB_DIR_IN as appropriate),
887                 buffer and length, and a user "context" value serving to
888                 uniquely identify each request.
889                 (It's usually a pointer to per-request data.)
890                 Flags can modify requests (not as many as supported for
891                 kernel drivers).
892                 </para>
893
894                 <para>Each request can specify a realtime signal number
895                 (between SIGRTMIN and SIGRTMAX, inclusive) to request a
896                 signal be sent when the request completes.
897                 </para>
898
899                 <para>When usbfs returns these urbs, the status value
900                 is updated, and the buffer may have been modified.
901                 Except for isochronous transfers, the actual_length is
902                 updated to say how many bytes were transferred; if the
903                 USBDEVFS_URB_DISABLE_SPD flag is set
904                 ("short packets are not OK"), if fewer bytes were read
905                 than were requested then you get an error report.
906                 </para>
907
908 <programlisting>struct usbdevfs_iso_packet_desc {
909         unsigned int                     length;
910         unsigned int                     actual_length;
911         unsigned int                     status;
912 };
913
914 struct usbdevfs_urb {
915         unsigned char                    type;
916         unsigned char                    endpoint;
917         int                              status;
918         unsigned int                     flags;
919         void                             *buffer;
920         int                              buffer_length;
921         int                              actual_length;
922         int                              start_frame;
923         int                              number_of_packets;
924         int                              error_count;
925         unsigned int                     signr;
926         void                             *usercontext;
927         struct usbdevfs_iso_packet_desc  iso_frame_desc[];
928 };</programlisting>
929
930                 <para> For these asynchronous requests, the file modification
931                 time reflects when the request was initiated.
932                 This contrasts with their use with the synchronous requests,
933                 where it reflects when requests complete.
934                 </para>
935
936                 <variablelist>
937
938                 <varlistentry><term>USBDEVFS_DISCARDURB</term>
939                     <listitem><para>
940                     <emphasis>TBS</emphasis>
941                     File modification time is not updated by this request.
942                     </para><para>
943                     </para></listitem></varlistentry>
944
945                 <varlistentry><term>USBDEVFS_DISCSIGNAL</term>
946                     <listitem><para>
947                     <emphasis>TBS</emphasis>
948                     File modification time is not updated by this request.
949                     </para><para>
950                     </para></listitem></varlistentry>
951
952                 <varlistentry><term>USBDEVFS_REAPURB</term>
953                     <listitem><para>
954                     <emphasis>TBS</emphasis>
955                     File modification time is not updated by this request.
956                     </para><para>
957                     </para></listitem></varlistentry>
958
959                 <varlistentry><term>USBDEVFS_REAPURBNDELAY</term>
960                     <listitem><para>
961                     <emphasis>TBS</emphasis>
962                     File modification time is not updated by this request.
963                     </para><para>
964                     </para></listitem></varlistentry>
965
966                 <varlistentry><term>USBDEVFS_SUBMITURB</term>
967                     <listitem><para>
968                     <emphasis>TBS</emphasis>
969                     </para><para>
970                     </para></listitem></varlistentry>
971
972                 </variablelist>
973             </sect2>
974
975         </sect1>
976
977     </chapter>
978
979 </book>
980 <!-- vim:syntax=sgml:sw=4
981 -->