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