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