summaryrefslogtreecommitdiff
path: root/Documentation/DocBook/writing_usb_driver.tmpl
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/DocBook/writing_usb_driver.tmpl')
-rw-r--r--Documentation/DocBook/writing_usb_driver.tmpl412
1 files changed, 0 insertions, 412 deletions
diff --git a/Documentation/DocBook/writing_usb_driver.tmpl b/Documentation/DocBook/writing_usb_driver.tmpl
deleted file mode 100644
index 3210dcf741c9..000000000000
--- a/Documentation/DocBook/writing_usb_driver.tmpl
+++ /dev/null
@@ -1,412 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
-
-<book id="USBDeviceDriver">
- <bookinfo>
- <title>Writing USB Device Drivers</title>
-
- <authorgroup>
- <author>
- <firstname>Greg</firstname>
- <surname>Kroah-Hartman</surname>
- <affiliation>
- <address>
- <email>greg@kroah.com</email>
- </address>
- </affiliation>
- </author>
- </authorgroup>
-
- <copyright>
- <year>2001-2002</year>
- <holder>Greg Kroah-Hartman</holder>
- </copyright>
-
- <legalnotice>
- <para>
- This documentation is free software; you can redistribute
- it and/or modify it under the terms of the GNU General Public
- License as published by the Free Software Foundation; either
- version 2 of the License, or (at your option) any later
- version.
- </para>
-
- <para>
- This program is distributed in the hope that it will be
- useful, but WITHOUT ANY WARRANTY; without even the implied
- warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- See the GNU General Public License for more details.
- </para>
-
- <para>
- You should have received a copy of the GNU General Public
- License along with this program; if not, write to the Free
- Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
- MA 02111-1307 USA
- </para>
-
- <para>
- For more details see the file COPYING in the source
- distribution of Linux.
- </para>
-
- <para>
- This documentation is based on an article published in
- Linux Journal Magazine, October 2001, Issue 90.
- </para>
- </legalnotice>
- </bookinfo>
-
-<toc></toc>
-
- <chapter id="intro">
- <title>Introduction</title>
- <para>
- The Linux USB subsystem has grown from supporting only two different
- types of devices in the 2.2.7 kernel (mice and keyboards), to over 20
- different types of devices in the 2.4 kernel. Linux currently supports
- almost all USB class devices (standard types of devices like keyboards,
- mice, modems, printers and speakers) and an ever-growing number of
- vendor-specific devices (such as USB to serial converters, digital
- cameras, Ethernet devices and MP3 players). For a full list of the
- different USB devices currently supported, see Resources.
- </para>
- <para>
- The remaining kinds of USB devices that do not have support on Linux are
- almost all vendor-specific devices. Each vendor decides to implement a
- custom protocol to talk to their device, so a custom driver usually needs
- to be created. Some vendors are open with their USB protocols and help
- with the creation of Linux drivers, while others do not publish them, and
- developers are forced to reverse-engineer. See Resources for some links
- to handy reverse-engineering tools.
- </para>
- <para>
- Because each different protocol causes a new driver to be created, I have
- written a generic USB driver skeleton, modelled after the pci-skeleton.c
- file in the kernel source tree upon which many PCI network drivers have
- been based. This USB skeleton can be found at drivers/usb/usb-skeleton.c
- in the kernel source tree. In this article I will walk through the basics
- of the skeleton driver, explaining the different pieces and what needs to
- be done to customize it to your specific device.
- </para>
- </chapter>
-
- <chapter id="basics">
- <title>Linux USB Basics</title>
- <para>
- If you are going to write a Linux USB driver, please become familiar with
- the USB protocol specification. It can be found, along with many other
- useful documents, at the USB home page (see Resources). An excellent
- introduction to the Linux USB subsystem can be found at the USB Working
- Devices List (see Resources). It explains how the Linux USB subsystem is
- structured and introduces the reader to the concept of USB urbs
- (USB Request Blocks), which are essential to USB drivers.
- </para>
- <para>
- The first thing a Linux USB driver needs to do is register itself with
- the Linux USB subsystem, giving it some information about which devices
- the driver supports and which functions to call when a device supported
- by the driver is inserted or removed from the system. All of this
- information is passed to the USB subsystem in the usb_driver structure.
- The skeleton driver declares a usb_driver as:
- </para>
- <programlisting>
-static struct usb_driver skel_driver = {
- .name = "skeleton",
- .probe = skel_probe,
- .disconnect = skel_disconnect,
- .fops = &amp;skel_fops,
- .minor = USB_SKEL_MINOR_BASE,
- .id_table = skel_table,
-};
- </programlisting>
- <para>
- The variable name is a string that describes the driver. It is used in
- informational messages printed to the system log. The probe and
- disconnect function pointers are called when a device that matches the
- information provided in the id_table variable is either seen or removed.
- </para>
- <para>
- The fops and minor variables are optional. Most USB drivers hook into
- another kernel subsystem, such as the SCSI, network or TTY subsystem.
- These types of drivers register themselves with the other kernel
- subsystem, and any user-space interactions are provided through that
- interface. But for drivers that do not have a matching kernel subsystem,
- such as MP3 players or scanners, a method of interacting with user space
- is needed. The USB subsystem provides a way to register a minor device
- number and a set of file_operations function pointers that enable this
- user-space interaction. The skeleton driver needs this kind of interface,
- so it provides a minor starting number and a pointer to its
- file_operations functions.
- </para>
- <para>
- The USB driver is then registered with a call to usb_register, usually in
- the driver's init function, as shown here:
- </para>
- <programlisting>
-static int __init usb_skel_init(void)
-{
- int result;
-
- /* register this driver with the USB subsystem */
- result = usb_register(&amp;skel_driver);
- if (result &lt; 0) {
- err(&quot;usb_register failed for the &quot;__FILE__ &quot;driver.&quot;
- &quot;Error number %d&quot;, result);
- return -1;
- }
-
- return 0;
-}
-module_init(usb_skel_init);
- </programlisting>
- <para>
- When the driver is unloaded from the system, it needs to deregister
- itself with the USB subsystem. This is done with the usb_deregister
- function:
- </para>
- <programlisting>
-static void __exit usb_skel_exit(void)
-{
- /* deregister this driver with the USB subsystem */
- usb_deregister(&amp;skel_driver);
-}
-module_exit(usb_skel_exit);
- </programlisting>
- <para>
- To enable the linux-hotplug system to load the driver automatically when
- the device is plugged in, you need to create a MODULE_DEVICE_TABLE. The
- following code tells the hotplug scripts that this module supports a
- single device with a specific vendor and product ID:
- </para>
- <programlisting>
-/* table of devices that work with this driver */
-static struct usb_device_id skel_table [] = {
- { USB_DEVICE(USB_SKEL_VENDOR_ID, USB_SKEL_PRODUCT_ID) },
- { } /* Terminating entry */
-};
-MODULE_DEVICE_TABLE (usb, skel_table);
- </programlisting>
- <para>
- There are other macros that can be used in describing a usb_device_id for
- drivers that support a whole class of USB drivers. See usb.h for more
- information on this.
- </para>
- </chapter>
-
- <chapter id="device">
- <title>Device operation</title>
- <para>
- When a device is plugged into the USB bus that matches the device ID
- pattern that your driver registered with the USB core, the probe function
- is called. The usb_device structure, interface number and the interface ID
- are passed to the function:
- </para>
- <programlisting>
-static int skel_probe(struct usb_interface *interface,
- const struct usb_device_id *id)
- </programlisting>
- <para>
- The driver now needs to verify that this device is actually one that it
- can accept. If so, it returns 0.
- If not, or if any error occurs during initialization, an errorcode
- (such as <literal>-ENOMEM</literal> or <literal>-ENODEV</literal>)
- is returned from the probe function.
- </para>
- <para>
- In the skeleton driver, we determine what end points are marked as bulk-in
- and bulk-out. We create buffers to hold the data that will be sent and
- received from the device, and a USB urb to write data to the device is
- initialized.
- </para>
- <para>
- Conversely, when the device is removed from the USB bus, the disconnect
- function is called with the device pointer. The driver needs to clean any
- private data that has been allocated at this time and to shut down any
- pending urbs that are in the USB system.
- </para>
- <para>
- Now that the device is plugged into the system and the driver is bound to
- the device, any of the functions in the file_operations structure that
- were passed to the USB subsystem will be called from a user program trying
- to talk to the device. The first function called will be open, as the
- program tries to open the device for I/O. We increment our private usage
- count and save a pointer to our internal structure in the file
- structure. This is done so that future calls to file operations will
- enable the driver to determine which device the user is addressing. All
- of this is done with the following code:
- </para>
- <programlisting>
-/* increment our usage count for the module */
-++skel->open_count;
-
-/* save our object in the file's private structure */
-file->private_data = dev;
- </programlisting>
- <para>
- After the open function is called, the read and write functions are called
- to receive and send data to the device. In the skel_write function, we
- receive a pointer to some data that the user wants to send to the device
- and the size of the data. The function determines how much data it can
- send to the device based on the size of the write urb it has created (this
- size depends on the size of the bulk out end point that the device has).
- Then it copies the data from user space to kernel space, points the urb to
- the data and submits the urb to the USB subsystem. This can be seen in
- the following code:
- </para>
- <programlisting>
-/* we can only write as much as 1 urb will hold */
-bytes_written = (count > skel->bulk_out_size) ? skel->bulk_out_size : count;
-
-/* copy the data from user space into our urb */
-copy_from_user(skel->write_urb->transfer_buffer, buffer, bytes_written);
-
-/* set up our urb */
-usb_fill_bulk_urb(skel->write_urb,
- skel->dev,
- usb_sndbulkpipe(skel->dev, skel->bulk_out_endpointAddr),
- skel->write_urb->transfer_buffer,
- bytes_written,
- skel_write_bulk_callback,
- skel);
-
-/* send the data out the bulk port */
-result = usb_submit_urb(skel->write_urb);
-if (result) {
- err(&quot;Failed submitting write urb, error %d&quot;, result);
-}
- </programlisting>
- <para>
- When the write urb is filled up with the proper information using the
- usb_fill_bulk_urb function, we point the urb's completion callback to call our
- own skel_write_bulk_callback function. This function is called when the
- urb is finished by the USB subsystem. The callback function is called in
- interrupt context, so caution must be taken not to do very much processing
- at that time. Our implementation of skel_write_bulk_callback merely
- reports if the urb was completed successfully or not and then returns.
- </para>
- <para>
- The read function works a bit differently from the write function in that
- we do not use an urb to transfer data from the device to the driver.
- Instead we call the usb_bulk_msg function, which can be used to send or
- receive data from a device without having to create urbs and handle
- urb completion callback functions. We call the usb_bulk_msg function,
- giving it a buffer into which to place any data received from the device
- and a timeout value. If the timeout period expires without receiving any
- data from the device, the function will fail and return an error message.
- This can be shown with the following code:
- </para>
- <programlisting>
-/* do an immediate bulk read to get data from the device */
-retval = usb_bulk_msg (skel->dev,
- usb_rcvbulkpipe (skel->dev,
- skel->bulk_in_endpointAddr),
- skel->bulk_in_buffer,
- skel->bulk_in_size,
- &amp;count, HZ*10);
-/* if the read was successful, copy the data to user space */
-if (!retval) {
- if (copy_to_user (buffer, skel->bulk_in_buffer, count))
- retval = -EFAULT;
- else
- retval = count;
-}
- </programlisting>
- <para>
- The usb_bulk_msg function can be very useful for doing single reads or
- writes to a device; however, if you need to read or write constantly to a
- device, it is recommended to set up your own urbs and submit them to the
- USB subsystem.
- </para>
- <para>
- When the user program releases the file handle that it has been using to
- talk to the device, the release function in the driver is called. In this
- function we decrement our private usage count and wait for possible
- pending writes:
- </para>
- <programlisting>
-/* decrement our usage count for the device */
---skel->open_count;
- </programlisting>
- <para>
- One of the more difficult problems that USB drivers must be able to handle
- smoothly is the fact that the USB device may be removed from the system at
- any point in time, even if a program is currently talking to it. It needs
- to be able to shut down any current reads and writes and notify the
- user-space programs that the device is no longer there. The following
- code (function <function>skel_delete</function>)
- is an example of how to do this: </para>
- <programlisting>
-static inline void skel_delete (struct usb_skel *dev)
-{
- kfree (dev->bulk_in_buffer);
- if (dev->bulk_out_buffer != NULL)
- usb_free_coherent (dev->udev, dev->bulk_out_size,
- dev->bulk_out_buffer,
- dev->write_urb->transfer_dma);
- usb_free_urb (dev->write_urb);
- kfree (dev);
-}
- </programlisting>
- <para>
- If a program currently has an open handle to the device, we reset the flag
- <literal>device_present</literal>. For
- every read, write, release and other functions that expect a device to be
- present, the driver first checks this flag to see if the device is
- still present. If not, it releases that the device has disappeared, and a
- -ENODEV error is returned to the user-space program. When the release
- function is eventually called, it determines if there is no device
- and if not, it does the cleanup that the skel_disconnect
- function normally does if there are no open files on the device (see
- Listing 5).
- </para>
- </chapter>
-
- <chapter id="iso">
- <title>Isochronous Data</title>
- <para>
- This usb-skeleton driver does not have any examples of interrupt or
- isochronous data being sent to or from the device. Interrupt data is sent
- almost exactly as bulk data is, with a few minor exceptions. Isochronous
- data works differently with continuous streams of data being sent to or
- from the device. The audio and video camera drivers are very good examples
- of drivers that handle isochronous data and will be useful if you also
- need to do this.
- </para>
- </chapter>
-
- <chapter id="Conclusion">
- <title>Conclusion</title>
- <para>
- Writing Linux USB device drivers is not a difficult task as the
- usb-skeleton driver shows. This driver, combined with the other current
- USB drivers, should provide enough examples to help a beginning author
- create a working driver in a minimal amount of time. The linux-usb-devel
- mailing list archives also contain a lot of helpful information.
- </para>
- </chapter>
-
- <chapter id="resources">
- <title>Resources</title>
- <para>
- The Linux USB Project: <ulink url="http://www.linux-usb.org">http://www.linux-usb.org/</ulink>
- </para>
- <para>
- Linux Hotplug Project: <ulink url="http://linux-hotplug.sourceforge.net">http://linux-hotplug.sourceforge.net/</ulink>
- </para>
- <para>
- Linux USB Working Devices List: <ulink url="http://www.qbik.ch/usb/devices">http://www.qbik.ch/usb/devices/</ulink>
- </para>
- <para>
- linux-usb-devel Mailing List Archives: <ulink url="http://marc.theaimsgroup.com/?l=linux-usb-devel">http://marc.theaimsgroup.com/?l=linux-usb-devel</ulink>
- </para>
- <para>
- Programming Guide for Linux USB Device Drivers: <ulink url="http://usb.cs.tum.edu/usbdoc">http://usb.cs.tum.edu/usbdoc</ulink>
- </para>
- <para>
- USB Home Page: <ulink url="http://www.usb.org">http://www.usb.org</ulink>
- </para>
- </chapter>
-
-</book>