Lines Matching +full:usb +full:- +full:c
1 .. _writing-usb-driver:
4 Writing USB Device Drivers
7 :Author: Greg Kroah-Hartman
12 The Linux USB subsystem has grown from supporting only two different
15 almost all USB class devices (standard types of devices like keyboards,
16 mice, modems, printers and speakers) and an ever-growing number of
17 vendor-specific devices (such as USB to serial converters, digital
19 different USB devices currently supported, see Resources.
21 The remaining kinds of USB devices that do not have support on Linux are
22 almost all vendor-specific devices. Each vendor decides to implement a
24 needs to be created. Some vendors are open with their USB protocols and
26 them, and developers are forced to reverse-engineer. See Resources for
27 some links to handy reverse-engineering tools.
30 have written a generic USB driver skeleton, modelled after the
31 pci-skeleton.c file in the kernel source tree upon which many PCI
32 network drivers have been based. This USB skeleton can be found at
33 drivers/usb/usb-skeleton.c in the kernel source tree. In this article I
38 Linux USB Basics
41 If you are going to write a Linux USB driver, please become familiar
42 with the USB protocol specification. It can be found, along with many
43 other useful documents, at the USB home page (see Resources). An
44 excellent introduction to the Linux USB subsystem can be found at the
45 USB Working Devices List (see Resources). It explains how the Linux USB
46 subsystem is structured and introduces the reader to the concept of USB
47 urbs (USB Request Blocks), which are essential to USB drivers.
49 The first thing a Linux USB driver needs to do is register itself with
50 the Linux USB subsystem, giving it some information about which devices
53 information is passed to the USB subsystem in the :c:type:`usb_driver`
54 structure. The skeleton driver declares a :c:type:`usb_driver` as::
72 The fops and minor variables are optional. Most USB drivers hook into
75 subsystem, and any user-space interactions are provided through that
78 is needed. The USB subsystem provides a way to register a minor device
79 number and a set of :c:type:`file_operations` function pointers that enable
80 this user-space interaction. The skeleton driver needs this kind of
82 :c:type:`file_operations` functions.
84 The USB driver is then registered with a call to :c:func:`usb_register`,
91 /* register this driver with the USB subsystem */
96 return -1;
105 itself with the USB subsystem. This is done with the :c:func:`usb_deregister`
110 /* deregister this driver with the USB subsystem */
116 To enable the linux-hotplug system to load the driver automatically when
126 MODULE_DEVICE_TABLE (usb, skel_table);
130 :c:type:`usb_device_id` for drivers that support a whole class of USB
131 drivers. See :ref:`usb.h <usb_header>` for more information on this.
136 When a device is plugged into the USB bus that matches the device ID
137 pattern that your driver registered with the USB core, the probe
138 function is called. The :c:type:`usb_device` structure, interface number and
147 initialization, an errorcode (such as ``-ENOMEM`` or ``-ENODEV``) is
151 bulk-in and bulk-out. We create buffers to hold the data that will be
152 sent and received from the device, and a USB urb to write data to the
155 Conversely, when the device is removed from the USB bus, the disconnect
158 any pending urbs that are in the USB system.
161 to the device, any of the functions in the :c:type:`file_operations` structure
162 that were passed to the USB subsystem will be called from a user program
171 ++skel->open_count;
174 file->private_data = dev;
184 space, points the urb to the data and submits the urb to the USB
188 bytes_written = (count > skel->bulk_out_size) ? skel->bulk_out_size : count;
191 copy_from_user(skel->write_urb->transfer_buffer, buffer, bytes_written);
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,
203 result = usb_submit_urb(skel->write_urb);
210 :c:func:`usb_fill_bulk_urb` function, we point the urb's completion callback
212 called when the urb is finished by the USB subsystem. The callback
220 driver. Instead we call the :c:func:`usb_bulk_msg` function, which can be used
222 handle urb completion callback functions. We call the :c:func:`usb_bulk_msg`
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,
237 if (copy_to_user (buffer, skel->bulk_in_buffer, count))
238 retval = -EFAULT;
244 The :c:func:`usb_bulk_msg` function can be very useful for doing single reads
247 the USB subsystem.
255 --skel->open_count;
258 One of the more difficult problems that USB drivers must be able to
259 handle smoothly is the fact that the USB device may be removed from the
262 notify the user-space programs that the device is no longer there. The
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);
282 that the device has disappeared, and a ``-ENODEV`` error is returned to the
283 user-space program. When the release function is eventually called, it
291 This usb-skeleton driver does not have any examples of interrupt or
302 Writing Linux USB device drivers is not a difficult task as the
303 usb-skeleton driver shows. This driver, combined with the other current
304 USB drivers, should provide enough examples to help a beginning author
305 create a working driver in a minimal amount of time. The linux-usb-devel
311 The Linux USB Project:
312 http://www.linux-usb.org/
315 http://linux-hotplug.sourceforge.net/
317 linux-usb Mailing List Archives:
318 https://lore.kernel.org/linux-usb/
320 Programming Guide for Linux USB Device Drivers:
323 USB Home Page: https://www.usb.org