1da177e4c3
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!
419 lines
17 KiB
XML
419 lines
17 KiB
XML
<?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, modeled 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, 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 = &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(&skel_driver);
|
|
if (result < 0) {
|
|
err("usb_register failed for the "__FILE__ "driver."
|
|
"Error number %d", result);
|
|
return -1;
|
|
}
|
|
|
|
return 0;
|
|
}
|
|
module_init(usb_skel_init);
|
|
</programlisting>
|
|
<para>
|
|
When the driver is unloaded from the system, it needs to unregister
|
|
itself with the USB subsystem. This is done with the usb_unregister
|
|
function:
|
|
</para>
|
|
<programlisting>
|
|
static void __exit usb_skel_exit(void)
|
|
{
|
|
/* deregister this driver with the USB subsystem */
|
|
usb_deregister(&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. The driver also unregisters
|
|
itself from the devfs subsystem with the call:
|
|
</para>
|
|
<programlisting>
|
|
/* remove our devfs node */
|
|
devfs_unregister(skel->devfs);
|
|
</programlisting>
|
|
<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 off 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 shown in
|
|
he 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("Failed submitting write urb, error %d", 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,
|
|
&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)
|
|
{
|
|
if (dev->bulk_in_buffer != NULL)
|
|
kfree (dev->bulk_in_buffer);
|
|
if (dev->bulk_out_buffer != NULL)
|
|
usb_buffer_free (dev->udev, dev->bulk_out_size,
|
|
dev->bulk_out_buffer,
|
|
dev->write_urb->transfer_dma);
|
|
if (dev->write_urb != NULL)
|
|
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>
|