diff options
Diffstat (limited to 'Documentation/DocBook/writing_usb_driver.tmpl')
| -rw-r--r-- | Documentation/DocBook/writing_usb_driver.tmpl | 412 |
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 = &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> |