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