| <?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 |
| (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 = &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 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(&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("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) |
| { |
| 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> |
