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 | |
34132326 | 46 | devices. USB uses a tree structure, with the host as the |
1da177e4 | 47 | root (the system's master), hubs as interior nodes, and |
34132326 | 48 | peripherals as leaves (and slaves). |
1da177e4 LT |
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 | ||
34132326 SB |
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. | |
1da177e4 LT |
65 | </para> |
66 | ||
34132326 | 67 | <para>USB 1.0 was announced in January 1996 and was revised |
1da177e4 LT |
68 | as USB 1.1 (with improvements in hub specification and |
69 | support for interrupt-out transfers) in September 1998. | |
34132326 SB |
70 | USB 2.0 was released in April 2000, adding high-speed |
71 | transfers and transaction-translating hubs (used for USB 1.1 | |
1da177e4 LT |
72 | and 1.0 backward compatibility). |
73 | </para> | |
74 | ||
34132326 SB |
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. | |
1da177e4 LT |
83 | </para> |
84 | ||
85 | <para>Linux can run inside USB devices as well as on | |
86 | the hosts that control the devices. | |
34132326 | 87 | But USB device drivers running inside those peripherals |
1da177e4 | 88 | don't do the same things as the ones running inside hosts, |
34132326 SB |
89 | so they've been given a different name: |
90 | <emphasis>gadget drivers</emphasis>. | |
91 | This document does not cover gadget drivers. | |
1da177e4 LT |
92 | </para> |
93 | ||
94 | </chapter> | |
95 | ||
96 | <chapter id="host"> | |
97 | <title>USB Host-Side API Model</title> | |
98 | ||
34132326 SB |
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>, | |
1da177e4 LT |
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 | ||
34132326 SB |
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) | |
1da177e4 LT |
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. | |
34132326 SB |
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. | |
1da177e4 LT |
127 | </para></listitem> |
128 | ||
34132326 | 129 | <listitem><para>Configurations have one or more "interfaces", each |
1da177e4 LT |
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 | |
34132326 | 155 | control and bulk messages. |
1da177e4 LT |
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><linux/usb_ch9.h></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 | |
ddae41be | 246 | !Edrivers/usb/core/driver.c |
1da177e4 LT |
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 | |
1fcb4454 | 285 | !Idrivers/usb/core/buffer.c |
1da177e4 LT |
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 | ||
06afff00 SB |
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(&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. | |
1da177e4 | 474 | </para> |
1da177e4 LT |
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 <linux/usb.h> | |
574 | #include <linux/usbdevice_fs.h> | |
575 | #include <asm/byteorder.h></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><linux/usb_ch9.h></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, &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><linux/usb.h></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 | |
d533f671 | 846 | applying to the current configuration. |
1da177e4 LT |
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 | --> |