1.. _writing-usb-driver:
2
3==========================
4Writing USB Device Drivers
5==========================
6
7:Author: Greg Kroah-Hartman
8
9Introduction
10============
11
12The Linux USB subsystem has grown from supporting only two different
13types of devices in the 2.2.7 kernel (mice and keyboards), to over 20
14different types of devices in the 2.4 kernel. Linux currently supports
15almost all USB class devices (standard types of devices like keyboards,
16mice, modems, printers and speakers) and an ever-growing number of
17vendor-specific devices (such as USB to serial converters, digital
18cameras, Ethernet devices and MP3 players). For a full list of the
19different USB devices currently supported, see Resources.
20
21The remaining kinds of USB devices that do not have support on Linux are
22almost all vendor-specific devices. Each vendor decides to implement a
23custom protocol to talk to their device, so a custom driver usually
24needs to be created. Some vendors are open with their USB protocols and
25help with the creation of Linux drivers, while others do not publish
26them, and developers are forced to reverse-engineer. See Resources for
27some links to handy reverse-engineering tools.
28
29Because each different protocol causes a new driver to be created, I
30have written a generic USB driver skeleton, modelled after the
31pci-skeleton.c file in the kernel source tree upon which many PCI
32network drivers have been based. This USB skeleton can be found at
33drivers/usb/usb-skeleton.c in the kernel source tree. In this article I
34will walk through the basics of the skeleton driver, explaining the
35different pieces and what needs to be done to customize it to your
36specific device.
37
38Linux USB Basics
39================
40
41If you are going to write a Linux USB driver, please become familiar
42with the USB protocol specification. It can be found, along with many
43other useful documents, at the USB home page (see Resources). An
44excellent introduction to the Linux USB subsystem can be found at the
45USB Working Devices List (see Resources). It explains how the Linux USB
46subsystem is structured and introduces the reader to the concept of USB
47urbs (USB Request Blocks), which are essential to USB drivers.
48
49The first thing a Linux USB driver needs to do is register itself with
50the Linux USB subsystem, giving it some information about which devices
51the driver supports and which functions to call when a device supported
52by the driver is inserted or removed from the system. All of this
53information is passed to the USB subsystem in the :c:type:`usb_driver`
54structure. The skeleton driver declares a :c:type:`usb_driver` as::
55
56    static struct usb_driver skel_driver = {
57	    .name        = "skeleton",
58	    .probe       = skel_probe,
59	    .disconnect  = skel_disconnect,
60	    .fops        = &skel_fops,
61	    .minor       = USB_SKEL_MINOR_BASE,
62	    .id_table    = skel_table,
63    };
64
65
66The variable name is a string that describes the driver. It is used in
67informational messages printed to the system log. The probe and
68disconnect function pointers are called when a device that matches the
69information provided in the ``id_table`` variable is either seen or
70removed.
71
72The fops and minor variables are optional. Most USB drivers hook into
73another kernel subsystem, such as the SCSI, network or TTY subsystem.
74These types of drivers register themselves with the other kernel
75subsystem, and any user-space interactions are provided through that
76interface. But for drivers that do not have a matching kernel subsystem,
77such as MP3 players or scanners, a method of interacting with user space
78is needed. The USB subsystem provides a way to register a minor device
79number and a set of :c:type:`file_operations` function pointers that enable
80this user-space interaction. The skeleton driver needs this kind of
81interface, so it provides a minor starting number and a pointer to its
82:c:type:`file_operations` functions.
83
84The USB driver is then registered with a call to :c:func:`usb_register`,
85usually in the driver's init function, as shown here::
86
87    static int __init usb_skel_init(void)
88    {
89	    int result;
90
91	    /* register this driver with the USB subsystem */
92	    result = usb_register(&skel_driver);
93	    if (result < 0) {
94		    err("usb_register failed for the "__FILE__ "driver."
95			"Error number %d", result);
96		    return -1;
97	    }
98
99	    return 0;
100    }
101    module_init(usb_skel_init);
102
103
104When the driver is unloaded from the system, it needs to deregister
105itself with the USB subsystem. This is done with the :c:func:`usb_deregister`
106function::
107
108    static void __exit usb_skel_exit(void)
109    {
110	    /* deregister this driver with the USB subsystem */
111	    usb_deregister(&skel_driver);
112    }
113    module_exit(usb_skel_exit);
114
115
116To enable the linux-hotplug system to load the driver automatically when
117the device is plugged in, you need to create a ``MODULE_DEVICE_TABLE``.
118The following code tells the hotplug scripts that this module supports a
119single device with a specific vendor and product ID::
120
121    /* table of devices that work with this driver */
122    static struct usb_device_id skel_table [] = {
123	    { USB_DEVICE(USB_SKEL_VENDOR_ID, USB_SKEL_PRODUCT_ID) },
124	    { }                      /* Terminating entry */
125    };
126    MODULE_DEVICE_TABLE (usb, skel_table);
127
128
129There are other macros that can be used in describing a struct
130:c:type:`usb_device_id` for drivers that support a whole class of USB
131drivers. See :ref:`usb.h <usb_header>` for more information on this.
132
133Device operation
134================
135
136When a device is plugged into the USB bus that matches the device ID
137pattern that your driver registered with the USB core, the probe
138function is called. The :c:type:`usb_device` structure, interface number and
139the interface ID are passed to the function::
140
141    static int skel_probe(struct usb_interface *interface,
142	const struct usb_device_id *id)
143
144
145The driver now needs to verify that this device is actually one that it
146can accept. If so, it returns 0. If not, or if any error occurs during
147initialization, an errorcode (such as ``-ENOMEM`` or ``-ENODEV``) is
148returned from the probe function.
149
150In the skeleton driver, we determine what end points are marked as
151bulk-in and bulk-out. We create buffers to hold the data that will be
152sent and received from the device, and a USB urb to write data to the
153device is initialized.
154
155Conversely, when the device is removed from the USB bus, the disconnect
156function is called with the device pointer. The driver needs to clean
157any private data that has been allocated at this time and to shut down
158any pending urbs that are in the USB system.
159
160Now that the device is plugged into the system and the driver is bound
161to the device, any of the functions in the :c:type:`file_operations` structure
162that were passed to the USB subsystem will be called from a user program
163trying to talk to the device. The first function called will be open, as
164the program tries to open the device for I/O. We increment our private
165usage count and save a pointer to our internal structure in the file
166structure. This is done so that future calls to file operations will
167enable the driver to determine which device the user is addressing. All
168of this is done with the following code::
169
170    /* increment our usage count for the module */
171    ++skel->open_count;
172
173    /* save our object in the file's private structure */
174    file->private_data = dev;
175
176
177After the open function is called, the read and write functions are
178called to receive and send data to the device. In the ``skel_write``
179function, we receive a pointer to some data that the user wants to send
180to the device and the size of the data. The function determines how much
181data it can send to the device based on the size of the write urb it has
182created (this size depends on the size of the bulk out end point that
183the device has). Then it copies the data from user space to kernel
184space, points the urb to the data and submits the urb to the USB
185subsystem. This can be seen in the following code::
186
187    /* we can only write as much as 1 urb will hold */
188    bytes_written = (count > skel->bulk_out_size) ? skel->bulk_out_size : count;
189
190    /* copy the data from user space into our urb */
191    copy_from_user(skel->write_urb->transfer_buffer, buffer, bytes_written);
192
193    /* set up our urb */
194    usb_fill_bulk_urb(skel->write_urb,
195		      skel->dev,
196		      usb_sndbulkpipe(skel->dev, skel->bulk_out_endpointAddr),
197		      skel->write_urb->transfer_buffer,
198		      bytes_written,
199		      skel_write_bulk_callback,
200		      skel);
201
202    /* send the data out the bulk port */
203    result = usb_submit_urb(skel->write_urb);
204    if (result) {
205	    err("Failed submitting write urb, error %d", result);
206    }
207
208
209When the write urb is filled up with the proper information using the
210:c:func:`usb_fill_bulk_urb` function, we point the urb's completion callback
211to call our own ``skel_write_bulk_callback`` function. This function is
212called when the urb is finished by the USB subsystem. The callback
213function is called in interrupt context, so caution must be taken not to
214do very much processing at that time. Our implementation of
215``skel_write_bulk_callback`` merely reports if the urb was completed
216successfully or not and then returns.
217
218The read function works a bit differently from the write function in
219that we do not use an urb to transfer data from the device to the
220driver. Instead we call the :c:func:`usb_bulk_msg` function, which can be used
221to send or receive data from a device without having to create urbs and
222handle urb completion callback functions. We call the :c:func:`usb_bulk_msg`
223function, giving it a buffer into which to place any data received from
224the device and a timeout value. If the timeout period expires without
225receiving any data from the device, the function will fail and return an
226error message. This can be shown with the following code::
227
228    /* do an immediate bulk read to get data from the device */
229    retval = usb_bulk_msg (skel->dev,
230			   usb_rcvbulkpipe (skel->dev,
231			   skel->bulk_in_endpointAddr),
232			   skel->bulk_in_buffer,
233			   skel->bulk_in_size,
234			   &count, HZ*10);
235    /* if the read was successful, copy the data to user space */
236    if (!retval) {
237	    if (copy_to_user (buffer, skel->bulk_in_buffer, count))
238		    retval = -EFAULT;
239	    else
240		    retval = count;
241    }
242
243
244The :c:func:`usb_bulk_msg` function can be very useful for doing single reads
245or writes to a device; however, if you need to read or write constantly to
246a device, it is recommended to set up your own urbs and submit them to
247the USB subsystem.
248
249When the user program releases the file handle that it has been using to
250talk to the device, the release function in the driver is called. In
251this function we decrement our private usage count and wait for possible
252pending writes::
253
254    /* decrement our usage count for the device */
255    --skel->open_count;
256
257
258One of the more difficult problems that USB drivers must be able to
259handle smoothly is the fact that the USB device may be removed from the
260system at any point in time, even if a program is currently talking to
261it. It needs to be able to shut down any current reads and writes and
262notify the user-space programs that the device is no longer there. The
263following code (function ``skel_delete``) is an example of how to do
264this::
265
266    static inline void skel_delete (struct usb_skel *dev)
267    {
268	kfree (dev->bulk_in_buffer);
269	if (dev->bulk_out_buffer != NULL)
270	    usb_free_coherent (dev->udev, dev->bulk_out_size,
271		dev->bulk_out_buffer,
272		dev->write_urb->transfer_dma);
273	usb_free_urb (dev->write_urb);
274	kfree (dev);
275    }
276
277
278If a program currently has an open handle to the device, we reset the
279flag ``device_present``. For every read, write, release and other
280functions that expect a device to be present, the driver first checks
281this flag to see if the device is still present. If not, it releases
282that the device has disappeared, and a ``-ENODEV`` error is returned to the
283user-space program. When the release function is eventually called, it
284determines if there is no device and if not, it does the cleanup that
285the ``skel_disconnect`` function normally does if there are no open files
286on the device (see Listing 5).
287
288Isochronous Data
289================
290
291This usb-skeleton driver does not have any examples of interrupt or
292isochronous data being sent to or from the device. Interrupt data is
293sent almost exactly as bulk data is, with a few minor exceptions.
294Isochronous data works differently with continuous streams of data being
295sent to or from the device. The audio and video camera drivers are very
296good examples of drivers that handle isochronous data and will be useful
297if you also need to do this.
298
299Conclusion
300==========
301
302Writing Linux USB device drivers is not a difficult task as the
303usb-skeleton driver shows. This driver, combined with the other current
304USB drivers, should provide enough examples to help a beginning author
305create a working driver in a minimal amount of time. The linux-usb-devel
306mailing list archives also contain a lot of helpful information.
307
308Resources
309=========
310
311The Linux USB Project:
312http://www.linux-usb.org/
313
314Linux Hotplug Project:
315http://linux-hotplug.sourceforge.net/
316
317Linux USB Working Devices List:
318http://www.qbik.ch/usb/devices/
319
320linux-usb-devel Mailing List Archives:
321http://marc.theaimsgroup.com/?l=linux-usb-devel
322
323Programming Guide for Linux USB Device Drivers:
324http://lmu.web.psi.ch/docu/manuals/software_manuals/linux_sl/usb_linux_programming_guide.pdf
325
326USB Home Page: http://www.usb.org
327