[media] DocBook/dvbproperty.xml: Better name the ISDB-T layers
[linux-2.6.git] / Documentation / DocBook / usb.tmpl
index 8a28f76..8d57c18 100644 (file)
 
     </chapter>
 
-<chapter><title>USB-Standard Types</title>
+<chapter id="types"><title>USB-Standard Types</title>
 
-    <para>In <filename>&lt;linux/usb_ch9.h&gt;</filename> you will find
+    <para>In <filename>&lt;linux/usb/ch9.h&gt;</filename> you will find
     the USB data types defined in chapter 9 of the USB specification.
     These data types are used throughout USB, and in APIs including
     this host side API, gadget APIs, and usbfs.
     </para>
 
-!Iinclude/linux/usb_ch9.h
+!Iinclude/linux/usb/ch9.h
 
     </chapter>
 
-<chapter><title>Host-Side Data Types and Macros</title>
+<chapter id="hostside"><title>Host-Side Data Types and Macros</title>
 
     <para>The host side API exposes several layers to drivers, some of
     which are more necessary than others.
 
     </chapter>
 
-    <chapter><title>USB Core APIs</title>
+    <chapter id="usbcore"><title>USB Core APIs</title>
 
     <para>There are two basic I/O models in the USB API.
     The most elemental one is asynchronous:  drivers submit requests
 !Edrivers/usb/core/hub.c
     </chapter>
 
-    <chapter><title>Host Controller APIs</title>
+    <chapter id="hcd"><title>Host Controller APIs</title>
 
     <para>These APIs are only for use by host controller drivers,
     most of which implement standard register interfaces such as
 !Idrivers/usb/core/buffer.c
     </chapter>
 
-    <chapter>
+    <chapter id="usbfs">
        <title>The USB Filesystem (usbfs)</title>
 
        <para>This chapter presents the Linux <emphasis>usbfs</emphasis>.
        <emphasis>usbdevfs</emphasis> although it wasn't solving what
        <emphasis>devfs</emphasis> was.
        Every USB device will appear in usbfs, regardless of whether or
-       not it has a kernel driver; but only devices with kernel drivers
-       show up in devfs.
+       not it has a kernel driver.
        </para>
 
-       <sect1>
+       <sect1 id="usbfs-files">
            <title>What files are in "usbfs"?</title>
 
            <para>Conventionally mounted at
 
        </sect1>
 
-       <sect1>
+       <sect1 id="usbfs-fstab">
            <title>Mounting and Access Control</title>
 
            <para>There are a number of mount options for usbfs, which will
 
        </sect1>
 
-       <sect1>
+       <sect1 id="usbfs-devices">
            <title>/proc/bus/usb/devices</title>
 
            <para>This file is handy for status viewing tools in user
            file in your Linux kernel sources.
            </para>
 
-           <para>Otherwise the main use for this file from programs
-           is to poll() it to get notifications of usb devices
-           as they're plugged or unplugged.
-           To see what changed, you'd need to read the file and
-           compare "before" and "after" contents, scan the filesystem,
-           or see its hotplug event.
+           <para>This file, in combination with the poll() system call, can
+           also be used to detect when devices are added or removed:
+<programlisting>int fd;
+struct pollfd pfd;
+
+fd = open("/proc/bus/usb/devices", O_RDONLY);
+pfd = { fd, POLLIN, 0 };
+for (;;) {
+       /* The first time through, this call will return immediately. */
+       poll(&amp;pfd, 1, -1);
+
+       /* To see what's changed, compare the file's previous and current
+          contents or scan the filesystem.  (Scanning is more precise.) */
+}</programlisting>
+           Note that this behavior is intended to be used for informational
+           and debug purposes.  It would be more appropriate to use programs
+           such as udev or HAL to initialize a device or start a user-mode
+           helper program, for instance.
            </para>
-
        </sect1>
 
-       <sect1>
+       <sect1 id="usbfs-bbbddd">
            <title>/proc/bus/usb/BBB/DDD</title>
 
            <para>Use these files in one of these basic ways:
            </sect1>
 
 
-       <sect1>
+       <sect1 id="usbfs-lifecycle">
            <title>Life Cycle of User Mode Drivers</title>
 
            <para>Such a driver first needs to find a device file
 
            </sect1>
 
-       <sect1><title>The ioctl() Requests</title>
+       <sect1 id="usbfs-ioctl"><title>The ioctl() Requests</title>
 
            <para>To use these ioctls, you need to include the following
            headers in your userspace program:
 #include &lt;asm/byteorder.h&gt;</programlisting>
            The standard USB device model requests, from "Chapter 9" of
            the USB 2.0 specification, are automatically included from
-           the <filename>&lt;linux/usb_ch9.h&gt;</filename> header.
+           the <filename>&lt;linux/usb/ch9.h&gt;</filename> header.
            </para>
 
            <para>Unless noted otherwise, the ioctl requests
            </para>
 
 
-           <sect2>
+           <sect2 id="usbfs-mgmt">
                <title>Management/Status Requests</title>
 
                <para>A number of usbfs requests don't deal very directly
@@ -680,7 +690,7 @@ usbdev_ioctl (int fd, int ifno, unsigned request, void *param)
                    </para><para>
                    This request lets kernel drivers talk to user mode code
                    through filesystem operations even when they don't create
-                   a charactor or block special device.
+                   a character or block special device.
                    It's also been used to do things like ask devices what
                    device special file should be used.
                    Two pre-defined ioctls are used
@@ -726,11 +736,11 @@ usbdev_ioctl (int fd, int ifno, unsigned request, void *param)
 
                </sect2>
 
-           <sect2>
+           <sect2 id="usbfs-sync">
                <title>Synchronous I/O Support</title>
 
                <para>Synchronous requests involve the kernel blocking
-               until until the user mode request completes, either by
+               until the user mode request completes, either by
                finishing successfully or by reporting an error.
                In most cases this is the simplest way to use usbfs,
                although as noted above it does prevent performing I/O
@@ -855,7 +865,7 @@ usbdev_ioctl (int fd, int ifno, unsigned request, void *param)
                </variablelist>
            </sect2>
 
-           <sect2>
+           <sect2 id="usbfs-async">
                <title>Asynchronous I/O Support</title>
 
                <para>As mentioned above, there are situations where it may be