About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / DocBook / usb.tmpl




Custom Search

Based on kernel version 3.13. Page generated on 2014-01-20 22:02 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" []>
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;
458	struct pollfd pfd;
459	
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);
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	 */
678	static int
679	usbdev_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	
913	struct 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	-->
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.