1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Chapter 3. Device operation</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="Writing USB Device Drivers"><link rel="up" href="index.html" title="Writing USB Device Drivers"><link rel="prev" href="basics.html" title="Chapter 2. Linux USB Basics"><link rel="next" href="iso.html" title="Chapter 4. Isochronous Data"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 3. Device operation</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="basics.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="iso.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="device"></a>Chapter 3. Device operation</h1></div></div></div><p> 2 When a device is plugged into the USB bus that matches the device ID 3 pattern that your driver registered with the USB core, the probe function 4 is called. The usb_device structure, interface number and the interface ID 5 are passed to the function: 6 </p><pre class="programlisting"> 7static int skel_probe(struct usb_interface *interface, 8 const struct usb_device_id *id) 9 </pre><p> 10 The driver now needs to verify that this device is actually one that it 11 can accept. If so, it returns 0. 12 If not, or if any error occurs during initialization, an errorcode 13 (such as <code class="literal">-ENOMEM</code> or <code class="literal">-ENODEV</code>) 14 is returned from the probe function. 15 </p><p> 16 In the skeleton driver, we determine what end points are marked as bulk-in 17 and bulk-out. We create buffers to hold the data that will be sent and 18 received from the device, and a USB urb to write data to the device is 19 initialized. 20 </p><p> 21 Conversely, when the device is removed from the USB bus, the disconnect 22 function is called with the device pointer. The driver needs to clean any 23 private data that has been allocated at this time and to shut down any 24 pending urbs that are in the USB system. 25 </p><p> 26 Now that the device is plugged into the system and the driver is bound to 27 the device, any of the functions in the file_operations structure that 28 were passed to the USB subsystem will be called from a user program trying 29 to talk to the device. The first function called will be open, as the 30 program tries to open the device for I/O. We increment our private usage 31 count and save a pointer to our internal structure in the file 32 structure. This is done so that future calls to file operations will 33 enable the driver to determine which device the user is addressing. All 34 of this is done with the following code: 35 </p><pre class="programlisting"> 36/* increment our usage count for the module */ 37++skel->open_count; 38 39/* save our object in the file's private structure */ 40file->private_data = dev; 41 </pre><p> 42 After the open function is called, the read and write functions are called 43 to receive and send data to the device. In the skel_write function, we 44 receive a pointer to some data that the user wants to send to the device 45 and the size of the data. The function determines how much data it can 46 send to the device based on the size of the write urb it has created (this 47 size depends on the size of the bulk out end point that the device has). 48 Then it copies the data from user space to kernel space, points the urb to 49 the data and submits the urb to the USB subsystem. This can be seen in 50 the following code: 51 </p><pre class="programlisting"> 52/* we can only write as much as 1 urb will hold */ 53bytes_written = (count > skel->bulk_out_size) ? skel->bulk_out_size : count; 54 55/* copy the data from user space into our urb */ 56copy_from_user(skel->write_urb->transfer_buffer, buffer, bytes_written); 57 58/* set up our urb */ 59usb_fill_bulk_urb(skel->write_urb, 60 skel->dev, 61 usb_sndbulkpipe(skel->dev, skel->bulk_out_endpointAddr), 62 skel->write_urb->transfer_buffer, 63 bytes_written, 64 skel_write_bulk_callback, 65 skel); 66 67/* send the data out the bulk port */ 68result = usb_submit_urb(skel->write_urb); 69if (result) { 70 err("Failed submitting write urb, error %d", result); 71} 72 </pre><p> 73 When the write urb is filled up with the proper information using the 74 usb_fill_bulk_urb function, we point the urb's completion callback to call our 75 own skel_write_bulk_callback function. This function is called when the 76 urb is finished by the USB subsystem. The callback function is called in 77 interrupt context, so caution must be taken not to do very much processing 78 at that time. Our implementation of skel_write_bulk_callback merely 79 reports if the urb was completed successfully or not and then returns. 80 </p><p> 81 The read function works a bit differently from the write function in that 82 we do not use an urb to transfer data from the device to the driver. 83 Instead we call the usb_bulk_msg function, which can be used to send or 84 receive data from a device without having to create urbs and handle 85 urb completion callback functions. We call the usb_bulk_msg function, 86 giving it a buffer into which to place any data received from the device 87 and a timeout value. If the timeout period expires without receiving any 88 data from the device, the function will fail and return an error message. 89 This can be shown with the following code: 90 </p><pre class="programlisting"> 91/* do an immediate bulk read to get data from the device */ 92retval = usb_bulk_msg (skel->dev, 93 usb_rcvbulkpipe (skel->dev, 94 skel->bulk_in_endpointAddr), 95 skel->bulk_in_buffer, 96 skel->bulk_in_size, 97 &count, HZ*10); 98/* if the read was successful, copy the data to user space */ 99if (!retval) { 100 if (copy_to_user (buffer, skel->bulk_in_buffer, count)) 101 retval = -EFAULT; 102 else 103 retval = count; 104} 105 </pre><p> 106 The usb_bulk_msg function can be very useful for doing single reads or 107 writes to a device; however, if you need to read or write constantly to a 108 device, it is recommended to set up your own urbs and submit them to the 109 USB subsystem. 110 </p><p> 111 When the user program releases the file handle that it has been using to 112 talk to the device, the release function in the driver is called. In this 113 function we decrement our private usage count and wait for possible 114 pending writes: 115 </p><pre class="programlisting"> 116/* decrement our usage count for the device */ 117--skel->open_count; 118 </pre><p> 119 One of the more difficult problems that USB drivers must be able to handle 120 smoothly is the fact that the USB device may be removed from the system at 121 any point in time, even if a program is currently talking to it. It needs 122 to be able to shut down any current reads and writes and notify the 123 user-space programs that the device is no longer there. The following 124 code (function <code class="function">skel_delete</code>) 125 is an example of how to do this: </p><pre class="programlisting"> 126static inline void skel_delete (struct usb_skel *dev) 127{ 128 kfree (dev->bulk_in_buffer); 129 if (dev->bulk_out_buffer != NULL) 130 usb_free_coherent (dev->udev, dev->bulk_out_size, 131 dev->bulk_out_buffer, 132 dev->write_urb->transfer_dma); 133 usb_free_urb (dev->write_urb); 134 kfree (dev); 135} 136 </pre><p> 137 If a program currently has an open handle to the device, we reset the flag 138 <code class="literal">device_present</code>. For 139 every read, write, release and other functions that expect a device to be 140 present, the driver first checks this flag to see if the device is 141 still present. If not, it releases that the device has disappeared, and a 142 -ENODEV error is returned to the user-space program. When the release 143 function is eventually called, it determines if there is no device 144 and if not, it does the cleanup that the skel_disconnect 145 function normally does if there are no open files on the device (see 146 Listing 5). 147 </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="basics.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="iso.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 2. Linux USB Basics </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 4. Isochronous Data</td></tr></table></div></body></html> 148