Documentation: convert USB to new format

+1 -1

Documentation/DocBook/Makefile

··· 9 9 DOCBOOKS := z8530book.xml \ 10 10 kernel-hacking.xml kernel-locking.xml deviceiobook.xml \ 11 11 writing_usb_driver.xml networking.xml \ 12 - kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \ 12 + kernel-api.xml filesystems.xml lsm.xml kgdb.xml \ 13 13 gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \ 14 14 genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \ 15 15 debugobjects.xml sh.xml regulator.xml \

-984

Documentation/DocBook/usb.tmpl

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

+1

Documentation/driver-api/index.rst

··· 20 20 sound 21 21 frame-buffer 22 22 input 23 + usb 23 24 spi 24 25 i2c 25 26 hsi

+748

Documentation/driver-api/usb.rst

··· 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*