0001 .. _writing-usb-driver:
0002
0003 ==========================
0004 Writing USB Device Drivers
0005 ==========================
0006
0007 :Author: Greg Kroah-Hartman
0008
0009 Introduction
0010 ============
0011
0012 The Linux USB subsystem has grown from supporting only two different
0013 types of devices in the 2.2.7 kernel (mice and keyboards), to over 20
0014 different types of devices in the 2.4 kernel. Linux currently supports
0015 almost all USB class devices (standard types of devices like keyboards,
0016 mice, modems, printers and speakers) and an ever-growing number of
0017 vendor-specific devices (such as USB to serial converters, digital
0018 cameras, Ethernet devices and MP3 players). For a full list of the
0019 different USB devices currently supported, see Resources.
0020
0021 The remaining kinds of USB devices that do not have support on Linux are
0022 almost all vendor-specific devices. Each vendor decides to implement a
0023 custom protocol to talk to their device, so a custom driver usually
0024 needs to be created. Some vendors are open with their USB protocols and
0025 help with the creation of Linux drivers, while others do not publish
0026 them, and developers are forced to reverse-engineer. See Resources for
0027 some links to handy reverse-engineering tools.
0028
0029 Because each different protocol causes a new driver to be created, I
0030 have written a generic USB driver skeleton, modelled after the
0031 pci-skeleton.c file in the kernel source tree upon which many PCI
0032 network drivers have been based. This USB skeleton can be found at
0033 drivers/usb/usb-skeleton.c in the kernel source tree. In this article I
0034 will walk through the basics of the skeleton driver, explaining the
0035 different pieces and what needs to be done to customize it to your
0036 specific device.
0037
0038 Linux USB Basics
0039 ================
0040
0041 If you are going to write a Linux USB driver, please become familiar
0042 with the USB protocol specification. It can be found, along with many
0043 other useful documents, at the USB home page (see Resources). An
0044 excellent introduction to the Linux USB subsystem can be found at the
0045 USB Working Devices List (see Resources). It explains how the Linux USB
0046 subsystem is structured and introduces the reader to the concept of USB
0047 urbs (USB Request Blocks), which are essential to USB drivers.
0048
0049 The first thing a Linux USB driver needs to do is register itself with
0050 the Linux USB subsystem, giving it some information about which devices
0051 the driver supports and which functions to call when a device supported
0052 by the driver is inserted or removed from the system. All of this
0053 information is passed to the USB subsystem in the :c:type:`usb_driver`
0054 structure. The skeleton driver declares a :c:type:`usb_driver` as::
0055
0056 static struct usb_driver skel_driver = {
0057 .name = "skeleton",
0058 .probe = skel_probe,
0059 .disconnect = skel_disconnect,
0060 .suspend = skel_suspend,
0061 .resume = skel_resume,
0062 .pre_reset = skel_pre_reset,
0063 .post_reset = skel_post_reset,
0064 .id_table = skel_table,
0065 .supports_autosuspend = 1,
0066 };
0067
0068
0069 The variable name is a string that describes the driver. It is used in
0070 informational messages printed to the system log. The probe and
0071 disconnect function pointers are called when a device that matches the
0072 information provided in the ``id_table`` variable is either seen or
0073 removed.
0074
0075 The fops and minor variables are optional. Most USB drivers hook into
0076 another kernel subsystem, such as the SCSI, network or TTY subsystem.
0077 These types of drivers register themselves with the other kernel
0078 subsystem, and any user-space interactions are provided through that
0079 interface. But for drivers that do not have a matching kernel subsystem,
0080 such as MP3 players or scanners, a method of interacting with user space
0081 is needed. The USB subsystem provides a way to register a minor device
0082 number and a set of :c:type:`file_operations` function pointers that enable
0083 this user-space interaction. The skeleton driver needs this kind of
0084 interface, so it provides a minor starting number and a pointer to its
0085 :c:type:`file_operations` functions.
0086
0087 The USB driver is then registered with a call to usb_register(),
0088 usually in the driver's init function, as shown here::
0089
0090 static int __init usb_skel_init(void)
0091 {
0092 int result;
0093
0094 /* register this driver with the USB subsystem */
0095 result = usb_register(&skel_driver);
0096 if (result < 0) {
0097 pr_err("usb_register failed for the %s driver. Error number %d\n",
0098 skel_driver.name, result);
0099 return -1;
0100 }
0101
0102 return 0;
0103 }
0104 module_init(usb_skel_init);
0105
0106
0107 When the driver is unloaded from the system, it needs to deregister
0108 itself with the USB subsystem. This is done with usb_deregister()
0109 function::
0110
0111 static void __exit usb_skel_exit(void)
0112 {
0113 /* deregister this driver with the USB subsystem */
0114 usb_deregister(&skel_driver);
0115 }
0116 module_exit(usb_skel_exit);
0117
0118
0119 To enable the linux-hotplug system to load the driver automatically when
0120 the device is plugged in, you need to create a ``MODULE_DEVICE_TABLE``.
0121 The following code tells the hotplug scripts that this module supports a
0122 single device with a specific vendor and product ID::
0123
0124 /* table of devices that work with this driver */
0125 static struct usb_device_id skel_table [] = {
0126 { USB_DEVICE(USB_SKEL_VENDOR_ID, USB_SKEL_PRODUCT_ID) },
0127 { } /* Terminating entry */
0128 };
0129 MODULE_DEVICE_TABLE (usb, skel_table);
0130
0131
0132 There are other macros that can be used in describing a struct
0133 :c:type:`usb_device_id` for drivers that support a whole class of USB
0134 drivers. See :ref:`usb.h <usb_header>` for more information on this.
0135
0136 Device operation
0137 ================
0138
0139 When a device is plugged into the USB bus that matches the device ID
0140 pattern that your driver registered with the USB core, the probe
0141 function is called. The :c:type:`usb_device` structure, interface number and
0142 the interface ID are passed to the function::
0143
0144 static int skel_probe(struct usb_interface *interface,
0145 const struct usb_device_id *id)
0146
0147
0148 The driver now needs to verify that this device is actually one that it
0149 can accept. If so, it returns 0. If not, or if any error occurs during
0150 initialization, an errorcode (such as ``-ENOMEM`` or ``-ENODEV``) is
0151 returned from the probe function.
0152
0153 In the skeleton driver, we determine what end points are marked as
0154 bulk-in and bulk-out. We create buffers to hold the data that will be
0155 sent and received from the device, and a USB urb to write data to the
0156 device is initialized.
0157
0158 Conversely, when the device is removed from the USB bus, the disconnect
0159 function is called with the device pointer. The driver needs to clean
0160 any private data that has been allocated at this time and to shut down
0161 any pending urbs that are in the USB system.
0162
0163 Now that the device is plugged into the system and the driver is bound
0164 to the device, any of the functions in the :c:type:`file_operations` structure
0165 that were passed to the USB subsystem will be called from a user program
0166 trying to talk to the device. The first function called will be open, as
0167 the program tries to open the device for I/O. We increment our private
0168 usage count and save a pointer to our internal structure in the file
0169 structure. This is done so that future calls to file operations will
0170 enable the driver to determine which device the user is addressing. All
0171 of this is done with the following code::
0172
0173 /* increment our usage count for the device */
0174 kref_get(&dev->kref);
0175
0176 /* save our object in the file's private structure */
0177 file->private_data = dev;
0178
0179
0180 After the open function is called, the read and write functions are
0181 called to receive and send data to the device. In the ``skel_write``
0182 function, we receive a pointer to some data that the user wants to send
0183 to the device and the size of the data. The function determines how much
0184 data it can send to the device based on the size of the write urb it has
0185 created (this size depends on the size of the bulk out end point that
0186 the device has). Then it copies the data from user space to kernel
0187 space, points the urb to the data and submits the urb to the USB
0188 subsystem. This can be seen in the following code::
0189
0190 /* we can only write as much as 1 urb will hold */
0191 size_t writesize = min_t(size_t, count, MAX_TRANSFER);
0192
0193 /* copy the data from user space into our urb */
0194 copy_from_user(buf, user_buffer, writesize);
0195
0196 /* set up our urb */
0197 usb_fill_bulk_urb(urb,
0198 dev->udev,
0199 usb_sndbulkpipe(dev->udev, dev->bulk_out_endpointAddr),
0200 buf,
0201 writesize,
0202 skel_write_bulk_callback,
0203 dev);
0204
0205 /* send the data out the bulk port */
0206 retval = usb_submit_urb(urb, GFP_KERNEL);
0207 if (retval) {
0208 dev_err(&dev->interface->dev,
0209 "%s - failed submitting write urb, error %d\n",
0210 __func__, retval);
0211 }
0212
0213
0214 When the write urb is filled up with the proper information using the
0215 :c:func:`usb_fill_bulk_urb` function, we point the urb's completion callback
0216 to call our own ``skel_write_bulk_callback`` function. This function is
0217 called when the urb is finished by the USB subsystem. The callback
0218 function is called in interrupt context, so caution must be taken not to
0219 do very much processing at that time. Our implementation of
0220 ``skel_write_bulk_callback`` merely reports if the urb was completed
0221 successfully or not and then returns.
0222
0223 The read function works a bit differently from the write function in
0224 that we do not use an urb to transfer data from the device to the
0225 driver. Instead we call the :c:func:`usb_bulk_msg` function, which can be used
0226 to send or receive data from a device without having to create urbs and
0227 handle urb completion callback functions. We call the :c:func:`usb_bulk_msg`
0228 function, giving it a buffer into which to place any data received from
0229 the device and a timeout value. If the timeout period expires without
0230 receiving any data from the device, the function will fail and return an
0231 error message. This can be shown with the following code::
0232
0233 /* do an immediate bulk read to get data from the device */
0234 retval = usb_bulk_msg (skel->dev,
0235 usb_rcvbulkpipe (skel->dev,
0236 skel->bulk_in_endpointAddr),
0237 skel->bulk_in_buffer,
0238 skel->bulk_in_size,
0239 &count, 5000);
0240 /* if the read was successful, copy the data to user space */
0241 if (!retval) {
0242 if (copy_to_user (buffer, skel->bulk_in_buffer, count))
0243 retval = -EFAULT;
0244 else
0245 retval = count;
0246 }
0247
0248
0249 The :c:func:`usb_bulk_msg` function can be very useful for doing single reads
0250 or writes to a device; however, if you need to read or write constantly to
0251 a device, it is recommended to set up your own urbs and submit them to
0252 the USB subsystem.
0253
0254 When the user program releases the file handle that it has been using to
0255 talk to the device, the release function in the driver is called. In
0256 this function we decrement our private usage count and wait for possible
0257 pending writes::
0258
0259 /* decrement our usage count for the device */
0260 --skel->open_count;
0261
0262
0263 One of the more difficult problems that USB drivers must be able to
0264 handle smoothly is the fact that the USB device may be removed from the
0265 system at any point in time, even if a program is currently talking to
0266 it. It needs to be able to shut down any current reads and writes and
0267 notify the user-space programs that the device is no longer there. The
0268 following code (function ``skel_delete``) is an example of how to do
0269 this::
0270
0271 static inline void skel_delete (struct usb_skel *dev)
0272 {
0273 kfree (dev->bulk_in_buffer);
0274 if (dev->bulk_out_buffer != NULL)
0275 usb_free_coherent (dev->udev, dev->bulk_out_size,
0276 dev->bulk_out_buffer,
0277 dev->write_urb->transfer_dma);
0278 usb_free_urb (dev->write_urb);
0279 kfree (dev);
0280 }
0281
0282
0283 If a program currently has an open handle to the device, we reset the
0284 flag ``device_present``. For every read, write, release and other
0285 functions that expect a device to be present, the driver first checks
0286 this flag to see if the device is still present. If not, it releases
0287 that the device has disappeared, and a ``-ENODEV`` error is returned to the
0288 user-space program. When the release function is eventually called, it
0289 determines if there is no device and if not, it does the cleanup that
0290 the ``skel_disconnect`` function normally does if there are no open files
0291 on the device (see Listing 5).
0292
0293 Isochronous Data
0294 ================
0295
0296 This usb-skeleton driver does not have any examples of interrupt or
0297 isochronous data being sent to or from the device. Interrupt data is
0298 sent almost exactly as bulk data is, with a few minor exceptions.
0299 Isochronous data works differently with continuous streams of data being
0300 sent to or from the device. The audio and video camera drivers are very
0301 good examples of drivers that handle isochronous data and will be useful
0302 if you also need to do this.
0303
0304 Conclusion
0305 ==========
0306
0307 Writing Linux USB device drivers is not a difficult task as the
0308 usb-skeleton driver shows. This driver, combined with the other current
0309 USB drivers, should provide enough examples to help a beginning author
0310 create a working driver in a minimal amount of time. The linux-usb-devel
0311 mailing list archives also contain a lot of helpful information.
0312
0313 Resources
0314 =========
0315
0316 The Linux USB Project:
0317 http://www.linux-usb.org/
0318
0319 Linux Hotplug Project:
0320 http://linux-hotplug.sourceforge.net/
0321
0322 linux-usb Mailing List Archives:
0323 https://lore.kernel.org/linux-usb/
0324
0325 Programming Guide for Linux USB Device Drivers:
0326 https://lmu.web.psi.ch/docu/manuals/software_manuals/linux_sl/usb_linux_programming_guide.pdf
0327
0328 USB Home Page: https://www.usb.org
