linux/Documentation/DocBook/usb.tmpl
<<
>>
Prefs
   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>&lt;linux/usb/ch9.h&gt;</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(&amp;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 &lt;linux/usb.h&gt;
 573#include &lt;linux/usbdevice_fs.h&gt;
 574#include &lt;asm/byteorder.h&gt;</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>&lt;linux/usb/ch9.h&gt;</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, &amp;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 character 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>&lt;linux/usb.h&gt;</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
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.