1<?xml version="1.0" encoding="UTF-8"?> 2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> 4 5<book id="Linux-USB-API"> 6 <bookinfo> 7 <title>The Linux-USB Host Side API</title> 8 9 <legalnotice> 10 <para> 11 This documentation is free software; you can redistribute 12 it and/or modify it under the terms of the GNU General Public 13 License as published by the Free Software Foundation; either 14 version 2 of the License, or (at your option) any later 15 version. 16 </para> 17 18 <para> 19 This program is distributed in the hope that it will be 20 useful, but WITHOUT ANY WARRANTY; without even the implied 21 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 22 See the GNU General Public License for more details. 23 </para> 24 25 <para> 26 You should have received a copy of the GNU General Public 27 License along with this program; if not, write to the Free 28 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, 29 MA 02111-1307 USA 30 </para> 31 32 <para> 33 For more details see the file COPYING in the source 34 distribution of Linux. 35 </para> 36 </legalnotice> 37 </bookinfo> 38 39<toc></toc> 40 41<chapter id="intro"> 42 <title>Introduction to USB on Linux</title> 43 44 <para>A Universal Serial Bus (USB) is used to connect a host, 45 such as a PC or workstation, to a number of peripheral 46 devices. USB uses a tree structure, with the host as the 47 root (the system's master), hubs as interior nodes, and 48 peripherals as leaves (and slaves). 49 Modern PCs support several such trees of USB devices, usually 50 one USB 2.0 tree (480 Mbit/sec each) with 51 a few USB 1.1 trees (12 Mbit/sec each) that are used when you 52 connect a USB 1.1 device directly to the machine's "root hub". 53 </para> 54 55 <para>That master/slave asymmetry was designed-in 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. 65 </para> 66 67 <para>USB 1.0 was announced in January 1996 and was revised 68 as USB 1.1 (with improvements in hub specification and 69 support for interrupt-out transfers) in September 1998. 70 USB 2.0 was released in April 2000, adding high-speed 71 transfers and transaction-translating hubs (used for USB 1.1 72 and 1.0 backward compatibility). 73 </para> 74 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. 83 </para> 84 85 <para>Linux can run inside USB devices as well as on 86 the hosts that control the devices. 87 But USB device drivers running inside those peripherals 88 don't do the same things as the ones running inside hosts, 89 so they've been given a different name: 90 <emphasis>gadget drivers</emphasis>. 91 This document does not cover gadget drivers. 92 </para> 93 94 </chapter> 95 96<chapter id="host"> 97 <title>USB Host-Side API Model</title> 98 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>, 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 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) 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. 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. 127 </para></listitem> 128 129 <listitem><para>Configurations have one or more "interfaces", each 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 155 control and bulk messages. 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 id="types"><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 id="hostside"><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 id="usbcore"><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 246!Edrivers/usb/core/driver.c 247!Edrivers/usb/core/usb.c 248!Edrivers/usb/core/hub.c 249 </chapter> 250 251 <chapter id="hcd"><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 285!Idrivers/usb/core/buffer.c 286 </chapter> 287 288 <chapter id="usbfs"> 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. 318 </para> 319 320 <sect1 id="usbfs-files"> 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 359 <sect1 id="usbfs-fstab"> 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 442 <sect1 id="usbfs-devices"> 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 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; 458struct pollfd pfd; 459 460fd = open("/proc/bus/usb/devices", O_RDONLY); 461pfd = { fd, POLLIN, 0 }; 462for (;;) { 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. 473 </para> 474 </sect1> 475 476 <sect1 id="usbfs-bbbddd"> 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 513 <sect1 id="usbfs-lifecycle"> 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 568 <sect1 id="usbfs-ioctl"><title>The ioctl() Requests</title> 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 577 the <filename><linux/usb/ch9.h></filename> header. 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 607 <sect2 id="usbfs-mgmt"> 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 */ 678static int 679usbdev_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 739 <sect2 id="usbfs-sync"> 740 <title>Synchronous I/O Support</title> 741 742 <para>Synchronous requests involve the kernel blocking 743 until the user mode request completes, either by 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 845 applying to the current configuration. 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 868 <sect2 id="usbfs-async"> 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 913struct 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--> 981