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