Commit | Line | Data |
---|---|---|
1da177e4 LT |
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 | --> |