About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / DocBook / usb.tmpl

Custom Search

Based on kernel version 4.7.2. Page generated on 2016-08-22 22:45 EST.

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" []>
5	<book id="Linux-USB-API">
6	 <bookinfo>
7	  <title>The Linux-USB Host Side API</title>
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>
18	   <para>
19	     This program is distributed in the hope that it will be
20	     useful, but WITHOUT ANY WARRANTY; without even the implied
22	     See the GNU General Public License for more details.
23	   </para>
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>
32	   <para>
33	     For more details see the file COPYING in the source
34	     distribution of Linux.
35	   </para>
36	  </legalnotice>
37	 </bookinfo>
39	<toc></toc>
41	<chapter id="intro">
42	    <title>Introduction to USB on Linux</title>
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>
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>
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>
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>
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>
94	    </chapter>
96	<chapter id="host">
97	    <title>USB Host-Side API Model</title>
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>
110	    <para>The device model seen by USB drivers is relatively complex.
111	    </para>
113	    <itemizedlist>
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>
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>
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>
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>
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>
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>
154		<listitem><para>The Linux USB API supports synchronous calls for
155		control and bulk messages.
156		It also supports asynchronous calls for all kinds of data transfer,
157		using request structures called "URBs" (USB Request Blocks).
158		</para></listitem>
160	    </itemizedlist>
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>
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>
186	    </chapter>
188	<chapter id="types"><title>USB-Standard Types</title>
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>
196	!Iinclude/linux/usb/ch9.h
198	    </chapter>
200	<chapter id="hostside"><title>Host-Side Data Types and Macros</title>
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>
210	!Iinclude/linux/usb.h
212	    </chapter>
214	    <chapter id="usbcore"><title>USB Core APIs</title>
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>
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>
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>
251	    <chapter id="hcd"><title>Host Controller APIs</title>
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>
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>
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>
283	!Edrivers/usb/core/hcd.c
284	!Edrivers/usb/core/hcd-pci.c
285	!Idrivers/usb/core/buffer.c
286	    </chapter>
288	    <chapter id="usbfs">
289		<title>The USB Filesystem (usbfs)</title>
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>
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>
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>
320		<sect1 id="usbfs-files">
321		    <title>What files are in "usbfs"?</title>
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>
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>
357		</sect1>
359		<sect1 id="usbfs-fstab">
360		    <title>Mounting and Access Control</title>
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>
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>
385		    <para>The mount options for usbfs, usable in /etc/fstab or
386		    in command line invocations of <emphasis>mount</emphasis>, are:
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>
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>
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>
431		    </para>
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>
440		</sect1>
442		<sect1 id="usbfs-devices">
443		    <title>/proc/bus/usb/devices</title>
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>
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;
458	struct pollfd pfd;
460	fd = open("/proc/bus/usb/devices", O_RDONLY);
461	pfd = { fd, POLLIN, 0 };
462	for (;;) {
463		/* The first time through, this call will return immediately. */
464		poll(&amp;pfd, 1, -1);
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>
476		<sect1 id="usbfs-bbbddd">
477		    <title>/proc/bus/usb/BBB/DDD</title>
479		    <para>Use these files in one of these basic ways:
480		    </para>
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>
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>
510		    </sect1>
513		<sect1 id="usbfs-lifecycle">
514		    <title>Life Cycle of User Mode Drivers</title>
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>
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>
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>
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>
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>
566		    </sect1>
568		<sect1 id="usbfs-ioctl"><title>The ioctl() Requests</title>
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>
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>
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 hub_wq (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>
607		    <sect2 id="usbfs-mgmt">
608			<title>Management/Status Requests</title>
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>
616			<variablelist>
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>
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>
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>
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	};
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	 */
678	static int
679	usbdev_ioctl (int fd, int ifno, unsigned request, void *param)
680	{
681	        struct usbdevfs_ioctl	wrapper;
683	        wrapper.ifno = ifno;
684	        wrapper.ioctl_code = request;
685	        wrapper.data = param;
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>
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>
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>
735			<varlistentry><term>USBDEVFS_DROP_PRIVILEGES</term>
736			    <listitem><para>This is used to relinquish the ability
737			    to do certain operations which are considered to be
738			    privileged on a usbfs file descriptor.
739			    This includes claiming arbitrary interfaces, resetting
740			    a device on which there are currently claimed interfaces
741			    from other users, and issuing USBDEVFS_IOCTL calls.
742			    The ioctl parameter is a 32 bit mask of interfaces
743			    the user is allowed to claim on this file descriptor.
744			    You may issue this ioctl more than one time to narrow
745			    said mask.
746			    </para></listitem></varlistentry>
747			</variablelist>
749			</sect2>
751		    <sect2 id="usbfs-sync">
752			<title>Synchronous I/O Support</title>
754			<para>Synchronous requests involve the kernel blocking
755			until the user mode request completes, either by
756			finishing successfully or by reporting an error.
757			In most cases this is the simplest way to use usbfs,
758			although as noted above it does prevent performing I/O
759			to more than one endpoint at a time.
760			</para>
762			<variablelist>
764			<varlistentry><term>USBDEVFS_BULK</term>
765			    <listitem><para>Issues a bulk read or write request to the
766			    device.
767			    The ioctl parameter is a pointer to this structure:
768	<programlisting>struct usbdevfs_bulktransfer {
769	        unsigned int  ep;
770	        unsigned int  len;
771	        unsigned int  timeout; /* in milliseconds */
772	        void          *data;
773	};</programlisting>
774			    </para><para>The "ep" value identifies a
775			    bulk endpoint number (1 to 15, as identified in an endpoint
776			    descriptor),
777			    masked with USB_DIR_IN when referring to an endpoint which
778			    sends data to the host from the device.
779			    The length of the data buffer is identified by "len";
780			    Recent kernels support requests up to about 128KBytes.
781			    <emphasis>FIXME say how read length is returned,
782			    and how short reads are handled.</emphasis>.
783			    </para></listitem></varlistentry>
785			<varlistentry><term>USBDEVFS_CLEAR_HALT</term>
786			    <listitem><para>Clears endpoint halt (stall) and
787			    resets the endpoint toggle.  This is only
788			    meaningful for bulk or interrupt endpoints.
789			    The ioctl parameter is an integer endpoint number
790			    (1 to 15, as identified in an endpoint descriptor),
791			    masked with USB_DIR_IN when referring to an endpoint which
792			    sends data to the host from the device.
793			    </para><para>
794			    Use this on bulk or interrupt endpoints which have
795			    stalled, returning <emphasis>-EPIPE</emphasis> status
796			    to a data transfer request.
797			    Do not issue the control request directly, since
798			    that could invalidate the host's record of the
799			    data toggle.
800			    </para></listitem></varlistentry>
802			<varlistentry><term>USBDEVFS_CONTROL</term>
803			    <listitem><para>Issues a control request to the device.
804			    The ioctl parameter points to a structure like this:
805	<programlisting>struct usbdevfs_ctrltransfer {
806	        __u8   bRequestType;
807	        __u8   bRequest;
808	        __u16  wValue;
809	        __u16  wIndex;
810	        __u16  wLength;
811	        __u32  timeout;  /* in milliseconds */
812	        void   *data;
813	};</programlisting>
814			    </para><para>
815			    The first eight bytes of this structure are the contents
816			    of the SETUP packet to be sent to the device; see the
817			    USB 2.0 specification for details.
818			    The bRequestType value is composed by combining a
819			    USB_TYPE_* value, a USB_DIR_* value, and a
820			    USB_RECIP_* value (from
821			    <emphasis>&lt;linux/usb.h&gt;</emphasis>).
822			    If wLength is nonzero, it describes the length of the data
823			    buffer, which is either written to the device
824			    (USB_DIR_OUT) or read from the device (USB_DIR_IN).
825			    </para><para>
826			    At this writing, you can't transfer more than 4 KBytes
827			    of data to or from a device; usbfs has a limit, and
828			    some host controller drivers have a limit.
829			    (That's not usually a problem.)
830			    <emphasis>Also</emphasis> there's no way to say it's
831			    not OK to get a short read back from the device.
832			    </para></listitem></varlistentry>
834			<varlistentry><term>USBDEVFS_RESET</term>
835			    <listitem><para>Does a USB level device reset.
836			    The ioctl parameter is ignored.
837			    After the reset, this rebinds all device interfaces.
838			    File modification time is not updated by this request.
839			    </para><warning><para>
840			    <emphasis>Avoid using this call</emphasis>
841			    until some usbcore bugs get fixed,
842			    since it does not fully synchronize device, interface,
843			    and driver (not just usbfs) state.
844			    </para></warning></listitem></varlistentry>
846			<varlistentry><term>USBDEVFS_SETINTERFACE</term>
847			    <listitem><para>Sets the alternate setting for an
848			    interface.  The ioctl parameter is a pointer to a
849			    structure like this:
850	<programlisting>struct usbdevfs_setinterface {
851	        unsigned int  interface;
852	        unsigned int  altsetting;
853	}; </programlisting>
854			    File modification time is not updated by this request.
855			    </para><para>
856			    Those struct members are from some interface descriptor
857			    applying to the current configuration.
858			    The interface number is the bInterfaceNumber value, and
859			    the altsetting number is the bAlternateSetting value.
860			    (This resets each endpoint in the interface.)
861			    </para></listitem></varlistentry>
863			<varlistentry><term>USBDEVFS_SETCONFIGURATION</term>
864			    <listitem><para>Issues the
865			    <function>usb_set_configuration</function> call
866			    for the device.
867			    The parameter is an integer holding the number of
868			    a configuration (bConfigurationValue from descriptor).
869			    File modification time is not updated by this request.
870			    </para><warning><para>
871			    <emphasis>Avoid using this call</emphasis>
872			    until some usbcore bugs get fixed,
873			    since it does not fully synchronize device, interface,
874			    and driver (not just usbfs) state.
875			    </para></warning></listitem></varlistentry>
877			</variablelist>
878		    </sect2>
880		    <sect2 id="usbfs-async">
881			<title>Asynchronous I/O Support</title>
883			<para>As mentioned above, there are situations where it may be
884			important to initiate concurrent operations from user mode code.
885			This is particularly important for periodic transfers
886			(interrupt and isochronous), but it can be used for other
887			kinds of USB requests too.
888			In such cases, the asynchronous requests described here
889			are essential.  Rather than submitting one request and having
890			the kernel block until it completes, the blocking is separate.
891			</para>
893			<para>These requests are packaged into a structure that
894			resembles the URB used by kernel device drivers.
895			(No POSIX Async I/O support here, sorry.)
896			It identifies the endpoint type (USBDEVFS_URB_TYPE_*),
897			endpoint (number, masked with USB_DIR_IN as appropriate),
898			buffer and length, and a user "context" value serving to
899			uniquely identify each request.
900			(It's usually a pointer to per-request data.)
901			Flags can modify requests (not as many as supported for
902			kernel drivers).
903			</para>
905			<para>Each request can specify a realtime signal number
906			(between SIGRTMIN and SIGRTMAX, inclusive) to request a
907			signal be sent when the request completes.
908			</para>
910			<para>When usbfs returns these urbs, the status value
911			is updated, and the buffer may have been modified.
912			Except for isochronous transfers, the actual_length is
913			updated to say how many bytes were transferred; if the
914			USBDEVFS_URB_DISABLE_SPD flag is set
915			("short packets are not OK"), if fewer bytes were read
916			than were requested then you get an error report.
917			</para>
919	<programlisting>struct usbdevfs_iso_packet_desc {
920	        unsigned int                     length;
921	        unsigned int                     actual_length;
922	        unsigned int                     status;
923	};
925	struct usbdevfs_urb {
926	        unsigned char                    type;
927	        unsigned char                    endpoint;
928	        int                              status;
929	        unsigned int                     flags;
930	        void                             *buffer;
931	        int                              buffer_length;
932	        int                              actual_length;
933	        int                              start_frame;
934	        int                              number_of_packets;
935	        int                              error_count;
936	        unsigned int                     signr;
937	        void                             *usercontext;
938	        struct usbdevfs_iso_packet_desc  iso_frame_desc[];
939	};</programlisting>
941			<para> For these asynchronous requests, the file modification
942			time reflects when the request was initiated.
943			This contrasts with their use with the synchronous requests,
944			where it reflects when requests complete.
945			</para>
947			<variablelist>
949			<varlistentry><term>USBDEVFS_DISCARDURB</term>
950			    <listitem><para>
951			    <emphasis>TBS</emphasis>
952			    File modification time is not updated by this request.
953			    </para><para>
954			    </para></listitem></varlistentry>
956			<varlistentry><term>USBDEVFS_DISCSIGNAL</term>
957			    <listitem><para>
958			    <emphasis>TBS</emphasis>
959			    File modification time is not updated by this request.
960			    </para><para>
961			    </para></listitem></varlistentry>
963			<varlistentry><term>USBDEVFS_REAPURB</term>
964			    <listitem><para>
965			    <emphasis>TBS</emphasis>
966			    File modification time is not updated by this request.
967			    </para><para>
968			    </para></listitem></varlistentry>
970			<varlistentry><term>USBDEVFS_REAPURBNDELAY</term>
971			    <listitem><para>
972			    <emphasis>TBS</emphasis>
973			    File modification time is not updated by this request.
974			    </para><para>
975			    </para></listitem></varlistentry>
977			<varlistentry><term>USBDEVFS_SUBMITURB</term>
978			    <listitem><para>
979			    <emphasis>TBS</emphasis>
980			    </para><para>
981			    </para></listitem></varlistentry>
983			</variablelist>
984		    </sect2>
986		</sect1>
988	    </chapter>
990	</book>
991	<!-- vim:syntax=sgml:sw=4
992	-->
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.