]>
Commit | Line | Data |
---|---|---|
dd0b38d8 ON |
1 | =========================== |
2 | The Linux-USB Host Side API | |
3 | =========================== | |
4 | ||
5 | Introduction to USB on Linux | |
6 | ============================ | |
7 | ||
8 | A Universal Serial Bus (USB) is used to connect a host, such as a PC or | |
9 | workstation, to a number of peripheral devices. USB uses a tree | |
10 | structure, with the host as the root (the system's master), hubs as | |
11 | interior nodes, and peripherals as leaves (and slaves). Modern PCs | |
12 | support several such trees of USB devices, usually | |
13 | a few USB 3.0 (5 GBit/s) or USB 3.1 (10 GBit/s) and some legacy | |
14 | USB 2.0 (480 MBit/s) busses just in case. | |
15 | ||
16 | That master/slave asymmetry was designed-in for a number of reasons, one | |
17 | being ease of use. It is not physically possible to mistake upstream and | |
18 | downstream or it does not matter with a type C plug (or they are built into the | |
19 | peripheral). Also, the host software doesn't need to deal with | |
20 | distributed auto-configuration since the pre-designated master node | |
21 | manages all that. | |
22 | ||
23 | Kernel developers added USB support to Linux early in the 2.2 kernel | |
24 | series and have been developing it further since then. Besides support | |
25 | for each new generation of USB, various host controllers gained support, | |
26 | new drivers for peripherals have been added and advanced features for latency | |
27 | measurement and improved power management introduced. | |
28 | ||
29 | Linux can run inside USB devices as well as on the hosts that control | |
30 | the devices. But USB device drivers running inside those peripherals | |
31 | don't do the same things as the ones running inside hosts, so they've | |
32 | been given a different name: *gadget drivers*. This document does not | |
33 | cover gadget drivers. | |
34 | ||
35 | USB Host-Side API Model | |
36 | ======================= | |
37 | ||
38 | Host-side drivers for USB devices talk to the "usbcore" APIs. There are | |
39 | two. One is intended for *general-purpose* drivers (exposed through | |
40 | driver frameworks), and the other is for drivers that are *part of the | |
41 | core*. Such core drivers include the *hub* driver (which manages trees | |
42 | of USB devices) and several different kinds of *host controller | |
43 | drivers*, which control individual busses. | |
44 | ||
45 | The device model seen by USB drivers is relatively complex. | |
46 | ||
47 | - USB supports four kinds of data transfers (control, bulk, interrupt, | |
48 | and isochronous). Two of them (control and bulk) use bandwidth as | |
49 | it's available, while the other two (interrupt and isochronous) are | |
50 | scheduled to provide guaranteed bandwidth. | |
51 | ||
52 | - The device description model includes one or more "configurations" | |
53 | per device, only one of which is active at a time. Devices are supposed | |
54 | to be capable of operating at lower than their top | |
55 | speeds and may provide a BOS descriptor showing the lowest speed they | |
56 | remain fully operational at. | |
57 | ||
58 | - From USB 3.0 on configurations have one or more "functions", which | |
59 | provide a common functionality and are grouped together for purposes | |
60 | of power management. | |
61 | ||
62 | - Configurations or functions have one or more "interfaces", each of which may have | |
63 | "alternate settings". Interfaces may be standardized by USB "Class" | |
64 | specifications, or may be specific to a vendor or device. | |
65 | ||
66 | USB device drivers actually bind to interfaces, not devices. Think of | |
67 | them as "interface drivers", though you may not see many devices | |
68 | where the distinction is important. *Most USB devices are simple, | |
69 | with only one function, one configuration, one interface, and one alternate | |
70 | setting.* | |
71 | ||
72 | - Interfaces have one or more "endpoints", each of which supports one | |
73 | type and direction of data transfer such as "bulk out" or "interrupt | |
74 | in". The entire configuration may have up to sixteen endpoints in | |
75 | each direction, allocated as needed among all the interfaces. | |
76 | ||
77 | - Data transfer on USB is packetized; each endpoint has a maximum | |
78 | packet size. Drivers must often be aware of conventions such as | |
79 | flagging the end of bulk transfers using "short" (including zero | |
80 | length) packets. | |
81 | ||
82 | - The Linux USB API supports synchronous calls for control and bulk | |
83 | messages. It also supports asynchronous calls for all kinds of data | |
84 | transfer, using request structures called "URBs" (USB Request | |
85 | Blocks). | |
86 | ||
87 | Accordingly, the USB Core API exposed to device drivers covers quite a | |
88 | lot of territory. You'll probably need to consult the USB 3.0 | |
89 | specification, available online from www.usb.org at no cost, as well as | |
90 | class or device specifications. | |
91 | ||
92 | The only host-side drivers that actually touch hardware (reading/writing | |
93 | registers, handling IRQs, and so on) are the HCDs. In theory, all HCDs | |
94 | provide the same functionality through the same API. In practice, that's | |
95 | becoming more true, but there are still differences | |
96 | that crop up especially with fault handling on the less common controllers. | |
97 | Different controllers don't | |
98 | necessarily report the same aspects of failures, and recovery from | |
99 | faults (including software-induced ones like unlinking an URB) isn't yet | |
100 | fully consistent. Device driver authors should make a point of doing | |
101 | disconnect testing (while the device is active) with each different host | |
102 | controller driver, to make sure drivers don't have bugs of their own as | |
103 | well as to make sure they aren't relying on some HCD-specific behavior. | |
104 | ||
105 | USB-Standard Types | |
106 | ================== | |
107 | ||
108 | In ``<linux/usb/ch9.h>`` you will find the USB data types defined in | |
109 | chapter 9 of the USB specification. These data types are used throughout | |
110 | USB, and in APIs including this host side API, gadget APIs, and usbfs. | |
111 | ||
112 | .. kernel-doc:: include/linux/usb/ch9.h | |
113 | :internal: | |
114 | ||
115 | Host-Side Data Types and Macros | |
116 | =============================== | |
117 | ||
118 | The host side API exposes several layers to drivers, some of which are | |
119 | more necessary than others. These support lifecycle models for host side | |
120 | drivers and devices, and support passing buffers through usbcore to some | |
121 | HCD that performs the I/O for the device driver. | |
122 | ||
123 | .. kernel-doc:: include/linux/usb.h | |
124 | :internal: | |
125 | ||
126 | USB Core APIs | |
127 | ============= | |
128 | ||
129 | There are two basic I/O models in the USB API. The most elemental one is | |
130 | asynchronous: drivers submit requests in the form of an URB, and the | |
131 | URB's completion callback handles the next step. All USB transfer types | |
132 | support that model, although there are special cases for control URBs | |
133 | (which always have setup and status stages, but may not have a data | |
134 | stage) and isochronous URBs (which allow large packets and include | |
135 | per-packet fault reports). Built on top of that is synchronous API | |
136 | support, where a driver calls a routine that allocates one or more URBs, | |
137 | submits them, and waits until they complete. There are synchronous | |
138 | wrappers for single-buffer control and bulk transfers (which are awkward | |
139 | to use in some driver disconnect scenarios), and for scatterlist based | |
140 | streaming i/o (bulk or interrupt). | |
141 | ||
142 | USB drivers need to provide buffers that can be used for DMA, although | |
143 | they don't necessarily need to provide the DMA mapping themselves. There | |
144 | are APIs to use used when allocating DMA buffers, which can prevent use | |
145 | of bounce buffers on some systems. In some cases, drivers may be able to | |
146 | rely on 64bit DMA to eliminate another kind of bounce buffer. | |
147 | ||
148 | .. kernel-doc:: drivers/usb/core/urb.c | |
149 | :export: | |
150 | ||
151 | .. kernel-doc:: drivers/usb/core/message.c | |
152 | :export: | |
153 | ||
154 | .. kernel-doc:: drivers/usb/core/file.c | |
155 | :export: | |
156 | ||
157 | .. kernel-doc:: drivers/usb/core/driver.c | |
158 | :export: | |
159 | ||
160 | .. kernel-doc:: drivers/usb/core/usb.c | |
161 | :export: | |
162 | ||
163 | .. kernel-doc:: drivers/usb/core/hub.c | |
164 | :export: | |
165 | ||
166 | Host Controller APIs | |
167 | ==================== | |
168 | ||
169 | These APIs are only for use by host controller drivers, most of which | |
170 | implement standard register interfaces such as XHCI, EHCI, OHCI, or UHCI. UHCI | |
171 | was one of the first interfaces, designed by Intel and also used by VIA; | |
172 | it doesn't do much in hardware. OHCI was designed later, to have the | |
173 | hardware do more work (bigger transfers, tracking protocol state, and so | |
174 | on). EHCI was designed with USB 2.0; its design has features that | |
175 | resemble OHCI (hardware does much more work) as well as UHCI (some parts | |
176 | of ISO support, TD list processing). XHCI was designed with USB 3.0. It | |
177 | continues to shift support for functionality into hardware. | |
178 | ||
179 | There are host controllers other than the "big three", although most PCI | |
180 | based controllers (and a few non-PCI based ones) use one of those | |
181 | interfaces. Not all host controllers use DMA; some use PIO, and there is | |
182 | also a simulator and a virtual host controller to pipe USB over the network. | |
183 | ||
184 | The same basic APIs are available to drivers for all those controllers. | |
185 | For historical reasons they are in two layers: :c:type:`struct | |
186 | usb_bus <usb_bus>` is a rather thin layer that became available | |
187 | in the 2.2 kernels, while :c:type:`struct usb_hcd <usb_hcd>` | |
188 | is a more featureful layer | |
189 | that lets HCDs share common code, to shrink driver size and | |
190 | significantly reduce hcd-specific behaviors. | |
191 | ||
192 | .. kernel-doc:: drivers/usb/core/hcd.c | |
193 | :export: | |
194 | ||
195 | .. kernel-doc:: drivers/usb/core/hcd-pci.c | |
196 | :export: | |
197 | ||
198 | .. kernel-doc:: drivers/usb/core/buffer.c | |
199 | :internal: | |
200 | ||
201 | The USB Filesystem (usbfs) | |
202 | ========================== | |
203 | ||
204 | This chapter presents the Linux *usbfs*. You may prefer to avoid writing | |
205 | new kernel code for your USB driver; that's the problem that usbfs set | |
206 | out to solve. User mode device drivers are usually packaged as | |
207 | applications or libraries, and may use usbfs through some programming | |
208 | library that wraps it. Such libraries include | |
209 | `libusb <http://libusb.sourceforge.net>`__ for C/C++, and | |
210 | `jUSB <http://jUSB.sourceforge.net>`__ for Java. | |
211 | ||
212 | **Note** | |
213 | ||
214 | This particular documentation is incomplete, especially with respect | |
215 | to the asynchronous mode. As of kernel 2.5.66 the code and this | |
216 | (new) documentation need to be cross-reviewed. | |
217 | ||
218 | Configure usbfs into Linux kernels by enabling the *USB filesystem* | |
219 | option (CONFIG_USB_DEVICEFS), and you get basic support for user mode | |
220 | USB device drivers. Until relatively recently it was often (confusingly) | |
221 | called *usbdevfs* although it wasn't solving what *devfs* was. Every USB | |
222 | device will appear in usbfs, regardless of whether or not it has a | |
223 | kernel driver. | |
224 | ||
225 | What files are in "usbfs"? | |
226 | -------------------------- | |
227 | ||
228 | Conventionally mounted at ``/proc/bus/usb``, usbfs features include: | |
229 | ||
230 | - ``/proc/bus/usb/devices`` ... a text file showing each of the USB | |
231 | devices on known to the kernel, and their configuration descriptors. | |
232 | You can also poll() this to learn about new devices. | |
233 | ||
234 | - ``/proc/bus/usb/BBB/DDD`` ... magic files exposing the each device's | |
235 | configuration descriptors, and supporting a series of ioctls for | |
236 | making device requests, including I/O to devices. (Purely for access | |
237 | by programs.) | |
238 | ||
239 | Each bus is given a number (BBB) based on when it was enumerated; within | |
240 | each bus, each device is given a similar number (DDD). Those BBB/DDD | |
241 | paths are not "stable" identifiers; expect them to change even if you | |
242 | always leave the devices plugged in to the same hub port. *Don't even | |
243 | think of saving these in application configuration files.* Stable | |
244 | identifiers are available, for user mode applications that want to use | |
245 | them. HID and networking devices expose these stable IDs, so that for | |
246 | example you can be sure that you told the right UPS to power down its | |
247 | second server. "usbfs" doesn't (yet) expose those IDs. | |
248 | ||
249 | Mounting and Access Control | |
250 | --------------------------- | |
251 | ||
252 | There are a number of mount options for usbfs, which will be of most | |
253 | interest to you if you need to override the default access control | |
254 | policy. That policy is that only root may read or write device files | |
255 | (``/proc/bus/BBB/DDD``) although anyone may read the ``devices`` or | |
256 | ``drivers`` files. I/O requests to the device also need the | |
257 | CAP_SYS_RAWIO capability, | |
258 | ||
259 | The significance of that is that by default, all user mode device | |
260 | drivers need super-user privileges. You can change modes or ownership in | |
261 | a driver setup when the device hotplugs, or maye just start the driver | |
262 | right then, as a privileged server (or some activity within one). That's | |
263 | the most secure approach for multi-user systems, but for single user | |
264 | systems ("trusted" by that user) it's more convenient just to grant | |
265 | everyone all access (using the *devmode=0666* option) so the driver can | |
266 | start whenever it's needed. | |
267 | ||
268 | The mount options for usbfs, usable in /etc/fstab or in command line | |
269 | invocations of *mount*, are: | |
270 | ||
271 | *busgid*\ =NNNNN | |
272 | Controls the GID used for the /proc/bus/usb/BBB directories. | |
273 | (Default: 0) | |
274 | ||
275 | *busmode*\ =MMM | |
276 | Controls the file mode used for the /proc/bus/usb/BBB directories. | |
277 | (Default: 0555) | |
278 | ||
279 | *busuid*\ =NNNNN | |
280 | Controls the UID used for the /proc/bus/usb/BBB directories. | |
281 | (Default: 0) | |
282 | ||
283 | *devgid*\ =NNNNN | |
284 | Controls the GID used for the /proc/bus/usb/BBB/DDD files. (Default: | |
285 | 0) | |
286 | ||
287 | *devmode*\ =MMM | |
288 | Controls the file mode used for the /proc/bus/usb/BBB/DDD files. | |
289 | (Default: 0644) | |
290 | ||
291 | *devuid*\ =NNNNN | |
292 | Controls the UID used for the /proc/bus/usb/BBB/DDD files. (Default: | |
293 | 0) | |
294 | ||
295 | *listgid*\ =NNNNN | |
296 | Controls the GID used for the /proc/bus/usb/devices and drivers | |
297 | files. (Default: 0) | |
298 | ||
299 | *listmode*\ =MMM | |
300 | Controls the file mode used for the /proc/bus/usb/devices and | |
301 | drivers files. (Default: 0444) | |
302 | ||
303 | *listuid*\ =NNNNN | |
304 | Controls the UID used for the /proc/bus/usb/devices and drivers | |
305 | files. (Default: 0) | |
306 | ||
307 | Note that many Linux distributions hard-wire the mount options for usbfs | |
308 | in their init scripts, such as ``/etc/rc.d/rc.sysinit``, rather than | |
309 | making it easy to set this per-system policy in ``/etc/fstab``. | |
310 | ||
311 | /proc/bus/usb/devices | |
312 | --------------------- | |
313 | ||
314 | This file is handy for status viewing tools in user mode, which can scan | |
315 | the text format and ignore most of it. More detailed device status | |
316 | (including class and vendor status) is available from device-specific | |
317 | files. For information about the current format of this file, see the | |
318 | ``Documentation/usb/proc_usb_info.txt`` file in your Linux kernel | |
319 | sources. | |
320 | ||
321 | This file, in combination with the poll() system call, can also be used | |
322 | to detect when devices are added or removed: | |
323 | ||
324 | :: | |
325 | ||
326 | int fd; | |
327 | struct pollfd pfd; | |
328 | ||
329 | fd = open("/proc/bus/usb/devices", O_RDONLY); | |
330 | pfd = { fd, POLLIN, 0 }; | |
331 | for (;;) { | |
332 | /* The first time through, this call will return immediately. */ | |
333 | poll(&pfd, 1, -1); | |
334 | ||
335 | /* To see what's changed, compare the file's previous and current | |
336 | contents or scan the filesystem. (Scanning is more precise.) */ | |
337 | } | |
338 | ||
339 | Note that this behavior is intended to be used for informational and | |
340 | debug purposes. It would be more appropriate to use programs such as | |
341 | udev or HAL to initialize a device or start a user-mode helper program, | |
342 | for instance. | |
343 | ||
344 | /proc/bus/usb/BBB/DDD | |
345 | --------------------- | |
346 | ||
347 | Use these files in one of these basic ways: | |
348 | ||
349 | *They can be read,* producing first the device descriptor (18 bytes) and | |
350 | then the descriptors for the current configuration. See the USB 2.0 spec | |
351 | for details about those binary data formats. You'll need to convert most | |
352 | multibyte values from little endian format to your native host byte | |
353 | order, although a few of the fields in the device descriptor (both of | |
354 | the BCD-encoded fields, and the vendor and product IDs) will be | |
355 | byteswapped for you. Note that configuration descriptors include | |
356 | descriptors for interfaces, altsettings, endpoints, and maybe additional | |
357 | class descriptors. | |
358 | ||
359 | *Perform USB operations* using *ioctl()* requests to make endpoint I/O | |
360 | requests (synchronously or asynchronously) or manage the device. These | |
361 | requests need the CAP_SYS_RAWIO capability, as well as filesystem | |
362 | access permissions. Only one ioctl request can be made on one of these | |
363 | device files at a time. This means that if you are synchronously reading | |
364 | an endpoint from one thread, you won't be able to write to a different | |
365 | endpoint from another thread until the read completes. This works for | |
366 | *half duplex* protocols, but otherwise you'd use asynchronous i/o | |
367 | requests. | |
368 | ||
369 | Life Cycle of User Mode Drivers | |
370 | ------------------------------- | |
371 | ||
372 | Such a driver first needs to find a device file for a device it knows | |
373 | how to handle. Maybe it was told about it because a ``/sbin/hotplug`` | |
374 | event handling agent chose that driver to handle the new device. Or | |
375 | maybe it's an application that scans all the /proc/bus/usb device files, | |
376 | and ignores most devices. In either case, it should :c:func:`read()` | |
377 | all the descriptors from the device file, and check them against what it | |
378 | knows how to handle. It might just reject everything except a particular | |
379 | vendor and product ID, or need a more complex policy. | |
380 | ||
381 | Never assume there will only be one such device on the system at a time! | |
382 | If your code can't handle more than one device at a time, at least | |
383 | detect when there's more than one, and have your users choose which | |
384 | device to use. | |
385 | ||
386 | Once your user mode driver knows what device to use, it interacts with | |
387 | it in either of two styles. The simple style is to make only control | |
388 | requests; some devices don't need more complex interactions than those. | |
389 | (An example might be software using vendor-specific control requests for | |
390 | some initialization or configuration tasks, with a kernel driver for the | |
391 | rest.) | |
392 | ||
393 | More likely, you need a more complex style driver: one using non-control | |
394 | endpoints, reading or writing data and claiming exclusive use of an | |
395 | interface. *Bulk* transfers are easiest to use, but only their sibling | |
396 | *interrupt* transfers work with low speed devices. Both interrupt and | |
397 | *isochronous* transfers offer service guarantees because their bandwidth | |
398 | is reserved. Such "periodic" transfers are awkward to use through usbfs, | |
399 | unless you're using the asynchronous calls. However, interrupt transfers | |
400 | can also be used in a synchronous "one shot" style. | |
401 | ||
402 | Your user-mode driver should never need to worry about cleaning up | |
403 | request state when the device is disconnected, although it should close | |
404 | its open file descriptors as soon as it starts seeing the ENODEV errors. | |
405 | ||
406 | The ioctl() Requests | |
407 | -------------------- | |
408 | ||
409 | To use these ioctls, you need to include the following headers in your | |
410 | userspace program: | |
411 | ||
412 | :: | |
413 | ||
414 | #include <linux/usb.h> | |
415 | #include <linux/usbdevice_fs.h> | |
416 | #include <asm/byteorder.h> | |
417 | ||
418 | The standard USB device model requests, from "Chapter 9" of the USB 2.0 | |
419 | specification, are automatically included from the ``<linux/usb/ch9.h>`` | |
420 | header. | |
421 | ||
422 | Unless noted otherwise, the ioctl requests described here will update | |
423 | the modification time on the usbfs file to which they are applied | |
424 | (unless they fail). A return of zero indicates success; otherwise, a | |
425 | standard USB error code is returned. (These are documented in | |
426 | ``Documentation/usb/error-codes.txt`` in your kernel sources.) | |
427 | ||
428 | Each of these files multiplexes access to several I/O streams, one per | |
429 | endpoint. Each device has one control endpoint (endpoint zero) which | |
430 | supports a limited RPC style RPC access. Devices are configured by | |
431 | hub_wq (in the kernel) setting a device-wide *configuration* that | |
432 | affects things like power consumption and basic functionality. The | |
433 | endpoints are part of USB *interfaces*, which may have *altsettings* | |
434 | affecting things like which endpoints are available. Many devices only | |
435 | have a single configuration and interface, so drivers for them will | |
436 | ignore configurations and altsettings. | |
437 | ||
438 | Management/Status Requests | |
439 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
440 | ||
441 | A number of usbfs requests don't deal very directly with device I/O. | |
442 | They mostly relate to device management and status. These are all | |
443 | synchronous requests. | |
444 | ||
445 | USBDEVFS_CLAIMINTERFACE | |
446 | This is used to force usbfs to claim a specific interface, which has | |
447 | not previously been claimed by usbfs or any other kernel driver. The | |
448 | ioctl parameter is an integer holding the number of the interface | |
449 | (bInterfaceNumber from descriptor). | |
450 | ||
451 | Note that if your driver doesn't claim an interface before trying to | |
452 | use one of its endpoints, and no other driver has bound to it, then | |
453 | the interface is automatically claimed by usbfs. | |
454 | ||
455 | This claim will be released by a RELEASEINTERFACE ioctl, or by | |
456 | closing the file descriptor. File modification time is not updated | |
457 | by this request. | |
458 | ||
459 | USBDEVFS_CONNECTINFO | |
460 | Says whether the device is lowspeed. The ioctl parameter points to a | |
461 | structure like this: | |
462 | ||
463 | :: | |
464 | ||
465 | struct usbdevfs_connectinfo { | |
466 | unsigned int devnum; | |
467 | unsigned char slow; | |
468 | }; | |
469 | ||
470 | File modification time is not updated by this request. | |
471 | ||
472 | *You can't tell whether a "not slow" device is connected at high | |
473 | speed (480 MBit/sec) or just full speed (12 MBit/sec).* You should | |
474 | know the devnum value already, it's the DDD value of the device file | |
475 | name. | |
476 | ||
477 | USBDEVFS_GETDRIVER | |
478 | Returns the name of the kernel driver bound to a given interface (a | |
479 | string). Parameter is a pointer to this structure, which is | |
480 | modified: | |
481 | ||
482 | :: | |
483 | ||
484 | struct usbdevfs_getdriver { | |
485 | unsigned int interface; | |
486 | char driver[USBDEVFS_MAXDRIVERNAME + 1]; | |
487 | }; | |
488 | ||
489 | File modification time is not updated by this request. | |
490 | ||
491 | USBDEVFS_IOCTL | |
492 | Passes a request from userspace through to a kernel driver that has | |
493 | an ioctl entry in the *struct usb_driver* it registered. | |
494 | ||
495 | :: | |
496 | ||
497 | struct usbdevfs_ioctl { | |
498 | int ifno; | |
499 | int ioctl_code; | |
500 | void *data; | |
501 | }; | |
502 | ||
503 | /* user mode call looks like this. | |
504 | * 'request' becomes the driver->ioctl() 'code' parameter. | |
505 | * the size of 'param' is encoded in 'request', and that data | |
506 | * is copied to or from the driver->ioctl() 'buf' parameter. | |
507 | */ | |
508 | static int | |
509 | usbdev_ioctl (int fd, int ifno, unsigned request, void *param) | |
510 | { | |
511 | struct usbdevfs_ioctl wrapper; | |
512 | ||
513 | wrapper.ifno = ifno; | |
514 | wrapper.ioctl_code = request; | |
515 | wrapper.data = param; | |
516 | ||
517 | return ioctl (fd, USBDEVFS_IOCTL, &wrapper); | |
518 | } | |
519 | ||
520 | File modification time is not updated by this request. | |
521 | ||
522 | This request lets kernel drivers talk to user mode code through | |
523 | filesystem operations even when they don't create a character or | |
524 | block special device. It's also been used to do things like ask | |
525 | devices what device special file should be used. Two pre-defined | |
526 | ioctls are used to disconnect and reconnect kernel drivers, so that | |
527 | user mode code can completely manage binding and configuration of | |
528 | devices. | |
529 | ||
530 | USBDEVFS_RELEASEINTERFACE | |
531 | This is used to release the claim usbfs made on interface, either | |
532 | implicitly or because of a USBDEVFS_CLAIMINTERFACE call, before the | |
533 | file descriptor is closed. The ioctl parameter is an integer holding | |
534 | the number of the interface (bInterfaceNumber from descriptor); File | |
535 | modification time is not updated by this request. | |
536 | ||
537 | **Warning** | |
538 | ||
539 | *No security check is made to ensure that the task which made | |
540 | the claim is the one which is releasing it. This means that user | |
541 | mode driver may interfere other ones.* | |
542 | ||
543 | USBDEVFS_RESETEP | |
544 | Resets the data toggle value for an endpoint (bulk or interrupt) to | |
545 | DATA0. The ioctl parameter is an integer endpoint number (1 to 15, | |
546 | as identified in the endpoint descriptor), with USB_DIR_IN added | |
547 | if the device's endpoint sends data to the host. | |
548 | ||
549 | **Warning** | |
550 | ||
551 | *Avoid using this request. It should probably be removed.* Using | |
552 | it typically means the device and driver will lose toggle | |
553 | synchronization. If you really lost synchronization, you likely | |
554 | need to completely handshake with the device, using a request | |
555 | like CLEAR_HALT or SET_INTERFACE. | |
556 | ||
557 | USBDEVFS_DROP_PRIVILEGES | |
558 | This is used to relinquish the ability to do certain operations | |
559 | which are considered to be privileged on a usbfs file descriptor. | |
560 | This includes claiming arbitrary interfaces, resetting a device on | |
561 | which there are currently claimed interfaces from other users, and | |
562 | issuing USBDEVFS_IOCTL calls. The ioctl parameter is a 32 bit mask | |
563 | of interfaces the user is allowed to claim on this file descriptor. | |
564 | You may issue this ioctl more than one time to narrow said mask. | |
565 | ||
566 | Synchronous I/O Support | |
567 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
568 | ||
569 | Synchronous requests involve the kernel blocking until the user mode | |
570 | request completes, either by finishing successfully or by reporting an | |
571 | error. In most cases this is the simplest way to use usbfs, although as | |
572 | noted above it does prevent performing I/O to more than one endpoint at | |
573 | a time. | |
574 | ||
575 | USBDEVFS_BULK | |
576 | Issues a bulk read or write request to the device. The ioctl | |
577 | parameter is a pointer to this structure: | |
578 | ||
579 | :: | |
580 | ||
581 | struct usbdevfs_bulktransfer { | |
582 | unsigned int ep; | |
583 | unsigned int len; | |
584 | unsigned int timeout; /* in milliseconds */ | |
585 | void *data; | |
586 | }; | |
587 | ||
588 | The "ep" value identifies a bulk endpoint number (1 to 15, as | |
589 | identified in an endpoint descriptor), masked with USB_DIR_IN when | |
590 | referring to an endpoint which sends data to the host from the | |
591 | device. The length of the data buffer is identified by "len"; Recent | |
592 | kernels support requests up to about 128KBytes. *FIXME say how read | |
593 | length is returned, and how short reads are handled.*. | |
594 | ||
595 | USBDEVFS_CLEAR_HALT | |
596 | Clears endpoint halt (stall) and resets the endpoint toggle. This is | |
597 | only meaningful for bulk or interrupt endpoints. The ioctl parameter | |
598 | is an integer endpoint number (1 to 15, as identified in an endpoint | |
599 | descriptor), masked with USB_DIR_IN when referring to an endpoint | |
600 | which sends data to the host from the device. | |
601 | ||
602 | Use this on bulk or interrupt endpoints which have stalled, | |
603 | returning *-EPIPE* status to a data transfer request. Do not issue | |
604 | the control request directly, since that could invalidate the host's | |
605 | record of the data toggle. | |
606 | ||
607 | USBDEVFS_CONTROL | |
608 | Issues a control request to the device. The ioctl parameter points | |
609 | to a structure like this: | |
610 | ||
611 | :: | |
612 | ||
613 | struct usbdevfs_ctrltransfer { | |
614 | __u8 bRequestType; | |
615 | __u8 bRequest; | |
616 | __u16 wValue; | |
617 | __u16 wIndex; | |
618 | __u16 wLength; | |
619 | __u32 timeout; /* in milliseconds */ | |
620 | void *data; | |
621 | }; | |
622 | ||
623 | The first eight bytes of this structure are the contents of the | |
624 | SETUP packet to be sent to the device; see the USB 2.0 specification | |
625 | for details. The bRequestType value is composed by combining a | |
626 | USB_TYPE_\* value, a USB_DIR_\* value, and a USB_RECIP_\* | |
627 | value (from *<linux/usb.h>*). If wLength is nonzero, it describes | |
628 | the length of the data buffer, which is either written to the device | |
629 | (USB_DIR_OUT) or read from the device (USB_DIR_IN). | |
630 | ||
631 | At this writing, you can't transfer more than 4 KBytes of data to or | |
632 | from a device; usbfs has a limit, and some host controller drivers | |
633 | have a limit. (That's not usually a problem.) *Also* there's no way | |
634 | to say it's not OK to get a short read back from the device. | |
635 | ||
636 | USBDEVFS_RESET | |
637 | Does a USB level device reset. The ioctl parameter is ignored. After | |
638 | the reset, this rebinds all device interfaces. File modification | |
639 | time is not updated by this request. | |
640 | ||
641 | **Warning** | |
642 | ||
643 | *Avoid using this call* until some usbcore bugs get fixed, since | |
644 | it does not fully synchronize device, interface, and driver (not | |
645 | just usbfs) state. | |
646 | ||
647 | USBDEVFS_SETINTERFACE | |
648 | Sets the alternate setting for an interface. The ioctl parameter is | |
649 | a pointer to a structure like this: | |
650 | ||
651 | :: | |
652 | ||
653 | struct usbdevfs_setinterface { | |
654 | unsigned int interface; | |
655 | unsigned int altsetting; | |
656 | }; | |
657 | ||
658 | File modification time is not updated by this request. | |
659 | ||
660 | Those struct members are from some interface descriptor applying to | |
661 | the current configuration. The interface number is the | |
662 | bInterfaceNumber value, and the altsetting number is the | |
663 | bAlternateSetting value. (This resets each endpoint in the | |
664 | interface.) | |
665 | ||
666 | USBDEVFS_SETCONFIGURATION | |
667 | Issues the :c:func:`usb_set_configuration()` call for the | |
668 | device. The parameter is an integer holding the number of a | |
669 | configuration (bConfigurationValue from descriptor). File | |
670 | modification time is not updated by this request. | |
671 | ||
672 | **Warning** | |
673 | ||
674 | *Avoid using this call* until some usbcore bugs get fixed, since | |
675 | it does not fully synchronize device, interface, and driver (not | |
676 | just usbfs) state. | |
677 | ||
678 | Asynchronous I/O Support | |
679 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
680 | ||
681 | As mentioned above, there are situations where it may be important to | |
682 | initiate concurrent operations from user mode code. This is particularly | |
683 | important for periodic transfers (interrupt and isochronous), but it can | |
684 | be used for other kinds of USB requests too. In such cases, the | |
685 | asynchronous requests described here are essential. Rather than | |
686 | submitting one request and having the kernel block until it completes, | |
687 | the blocking is separate. | |
688 | ||
689 | These requests are packaged into a structure that resembles the URB used | |
690 | by kernel device drivers. (No POSIX Async I/O support here, sorry.) It | |
691 | identifies the endpoint type (USBDEVFS_URB_TYPE_\*), endpoint | |
692 | (number, masked with USB_DIR_IN as appropriate), buffer and length, | |
693 | and a user "context" value serving to uniquely identify each request. | |
694 | (It's usually a pointer to per-request data.) Flags can modify requests | |
695 | (not as many as supported for kernel drivers). | |
696 | ||
697 | Each request can specify a realtime signal number (between SIGRTMIN and | |
698 | SIGRTMAX, inclusive) to request a signal be sent when the request | |
699 | completes. | |
700 | ||
701 | When usbfs returns these urbs, the status value is updated, and the | |
702 | buffer may have been modified. Except for isochronous transfers, the | |
703 | actual_length is updated to say how many bytes were transferred; if the | |
704 | USBDEVFS_URB_DISABLE_SPD flag is set ("short packets are not OK"), if | |
705 | fewer bytes were read than were requested then you get an error report. | |
706 | ||
707 | :: | |
708 | ||
709 | struct usbdevfs_iso_packet_desc { | |
710 | unsigned int length; | |
711 | unsigned int actual_length; | |
712 | unsigned int status; | |
713 | }; | |
714 | ||
715 | struct usbdevfs_urb { | |
716 | unsigned char type; | |
717 | unsigned char endpoint; | |
718 | int status; | |
719 | unsigned int flags; | |
720 | void *buffer; | |
721 | int buffer_length; | |
722 | int actual_length; | |
723 | int start_frame; | |
724 | int number_of_packets; | |
725 | int error_count; | |
726 | unsigned int signr; | |
727 | void *usercontext; | |
728 | struct usbdevfs_iso_packet_desc iso_frame_desc[]; | |
729 | }; | |
730 | ||
731 | For these asynchronous requests, the file modification time reflects | |
732 | when the request was initiated. This contrasts with their use with the | |
733 | synchronous requests, where it reflects when requests complete. | |
734 | ||
735 | USBDEVFS_DISCARDURB | |
736 | *TBS* File modification time is not updated by this request. | |
737 | ||
738 | USBDEVFS_DISCSIGNAL | |
739 | *TBS* File modification time is not updated by this request. | |
740 | ||
741 | USBDEVFS_REAPURB | |
742 | *TBS* File modification time is not updated by this request. | |
743 | ||
744 | USBDEVFS_REAPURBNDELAY | |
745 | *TBS* File modification time is not updated by this request. | |
746 | ||
747 | USBDEVFS_SUBMITURB | |
748 | *TBS* |