1Revised: 2000-Dec-05. 2Again: 2002-Jul-06 3Again: 2005-Sep-19 4 5 NOTE: 6 7 The USB subsystem now has a substantial section in "The Linux Kernel API" 8 guide (in Documentation/DocBook), generated from the current source 9 code. This particular documentation file isn't particularly current or 10 complete; don't rely on it except for a quick overview. 11 12 131.1. Basic concept or 'What is an URB?' 14 15The basic idea of the new driver is message passing, the message itself is 16called USB Request Block, or URB for short. 17 18- An URB consists of all relevant information to execute any USB transaction 19 and deliver the data and status back. 20 21- Execution of an URB is inherently an asynchronous operation, i.e. the 22 usb_submit_urb(urb) call returns immediately after it has successfully 23 queued the requested action. 24 25- Transfers for one URB can be canceled with usb_unlink_urb(urb) at any time. 26 27- Each URB has a completion handler, which is called after the action 28 has been successfully completed or canceled. The URB also contains a 29 context-pointer for passing information to the completion handler. 30 31- Each endpoint for a device logically supports a queue of requests. 32 You can fill that queue, so that the USB hardware can still transfer 33 data to an endpoint while your driver handles completion of another. 34 This maximizes use of USB bandwidth, and supports seamless streaming 35 of data to (or from) devices when using periodic transfer modes. 36 37 381.2. The URB structure 39 40Some of the fields in an URB are: 41 42struct urb 43{ 44// (IN) device and pipe specify the endpoint queue 45 struct usb_device *dev; // pointer to associated USB device 46 unsigned int pipe; // endpoint information 47 48 unsigned int transfer_flags; // ISO_ASAP, SHORT_NOT_OK, etc. 49 50// (IN) all urbs need completion routines 51 void *context; // context for completion routine 52 void (*complete)(struct urb *); // pointer to completion routine 53 54// (OUT) status after each completion 55 int status; // returned status 56 57// (IN) buffer used for data transfers 58 void *transfer_buffer; // associated data buffer 59 int transfer_buffer_length; // data buffer length 60 int number_of_packets; // size of iso_frame_desc 61 62// (OUT) sometimes only part of CTRL/BULK/INTR transfer_buffer is used 63 int actual_length; // actual data buffer length 64 65// (IN) setup stage for CTRL (pass a struct usb_ctrlrequest) 66 unsigned char* setup_packet; // setup packet (control only) 67 68// Only for PERIODIC transfers (ISO, INTERRUPT) 69 // (IN/OUT) start_frame is set unless ISO_ASAP isn't set 70 int start_frame; // start frame 71 int interval; // polling interval 72 73 // ISO only: packets are only "best effort"; each can have errors 74 int error_count; // number of errors 75 struct usb_iso_packet_descriptor iso_frame_desc[0]; 76}; 77 78Your driver must create the "pipe" value using values from the appropriate 79endpoint descriptor in an interface that it's claimed. 80 81 821.3. How to get an URB? 83 84URBs are allocated with the following call 85 86 struct urb *usb_alloc_urb(int isoframes, int mem_flags) 87 88Return value is a pointer to the allocated URB, 0 if allocation failed. 89The parameter isoframes specifies the number of isochronous transfer frames 90you want to schedule. For CTRL/BULK/INT, use 0. The mem_flags parameter 91holds standard memory allocation flags, letting you control (among other 92things) whether the underlying code may block or not. 93 94To free an URB, use 95 96 void usb_free_urb(struct urb *urb) 97 98You may free an urb that you've submitted, but which hasn't yet been 99returned to you in a completion callback. It will automatically be 100deallocated when it is no longer in use. 101 102 1031.4. What has to be filled in? 104 105Depending on the type of transaction, there are some inline functions 106defined in <linux/usb.h> to simplify the initialization, such as 107fill_control_urb() and fill_bulk_urb(). In general, they need the usb 108device pointer, the pipe (usual format from usb.h), the transfer buffer, 109the desired transfer length, the completion handler, and its context. 110Take a look at the some existing drivers to see how they're used. 111 112Flags: 113For ISO there are two startup behaviors: Specified start_frame or ASAP. 114For ASAP set URB_ISO_ASAP in transfer_flags. 115 116If short packets should NOT be tolerated, set URB_SHORT_NOT_OK in 117transfer_flags. 118 119 1201.5. How to submit an URB? 121 122Just call 123 124 int usb_submit_urb(struct urb *urb, int mem_flags) 125 126The mem_flags parameter, such as SLAB_ATOMIC, controls memory allocation, 127such as whether the lower levels may block when memory is tight. 128 129It immediately returns, either with status 0 (request queued) or some 130error code, usually caused by the following: 131 132- Out of memory (-ENOMEM) 133- Unplugged device (-ENODEV) 134- Stalled endpoint (-EPIPE) 135- Too many queued ISO transfers (-EAGAIN) 136- Too many requested ISO frames (-EFBIG) 137- Invalid INT interval (-EINVAL) 138- More than one packet for INT (-EINVAL) 139 140After submission, urb->status is -EINPROGRESS; however, you should never 141look at that value except in your completion callback. 142 143For isochronous endpoints, your completion handlers should (re)submit 144URBs to the same endpoint with the ISO_ASAP flag, using multi-buffering, 145to get seamless ISO streaming. 146 147 1481.6. How to cancel an already running URB? 149 150There are two ways to cancel an URB you've submitted but which hasn't 151been returned to your driver yet. For an asynchronous cancel, call 152 153 int usb_unlink_urb(struct urb *urb) 154 155It removes the urb from the internal list and frees all allocated 156HW descriptors. The status is changed to reflect unlinking. Note 157that the URB will not normally have finished when usb_unlink_urb() 158returns; you must still wait for the completion handler to be called. 159 160To cancel an URB synchronously, call 161 162 void usb_kill_urb(struct urb *urb) 163 164It does everything usb_unlink_urb does, and in addition it waits 165until after the URB has been returned and the completion handler 166has finished. It also marks the URB as temporarily unusable, so 167that if the completion handler or anyone else tries to resubmit it 168they will get a -EPERM error. Thus you can be sure that when 169usb_kill_urb() returns, the URB is totally idle. 170 171There is a lifetime issue to consider. An URB may complete at any 172time, and the completion handler may free the URB. If this happens 173while usb_unlink_urb or usb_kill_urb is running, it will cause a 174memory-access violation. The driver is responsible for avoiding this, 175which often means some sort of lock will be needed to prevent the URB 176from being deallocated while it is still in use. 177 178On the other hand, since usb_unlink_urb may end up calling the 179completion handler, the handler must not take any lock that is held 180when usb_unlink_urb is invoked. The general solution to this problem 181is to increment the URB's reference count while holding the lock, then 182drop the lock and call usb_unlink_urb or usb_kill_urb, and then 183decrement the URB's reference count. You increment the reference 184count by calling 185 186 struct urb *usb_get_urb(struct urb *urb) 187 188(ignore the return value; it is the same as the argument) and 189decrement the reference count by calling usb_free_urb. Of course, 190none of this is necessary if there's no danger of the URB being freed 191by the completion handler. 192 193 1941.7. What about the completion handler? 195 196The handler is of the following type: 197 198 typedef void (*usb_complete_t)(struct urb *) 199 200I.e., it gets the URB that caused the completion call. In the completion 201handler, you should have a look at urb->status to detect any USB errors. 202Since the context parameter is included in the URB, you can pass 203information to the completion handler. 204 205Note that even when an error (or unlink) is reported, data may have been 206transferred. That's because USB transfers are packetized; it might take 207sixteen packets to transfer your 1KByte buffer, and ten of them might 208have transferred successfully before the completion was called. 209 210 211NOTE: ***** WARNING ***** 212NEVER SLEEP IN A COMPLETION HANDLER. These are often called in atomic 213context. 214 215In the current kernel, completion handlers run with local interrupts 216disabled, but in the future this will be changed, so don't assume that 217local IRQs are always disabled inside completion handlers. 218 2191.8. How to do isochronous (ISO) transfers? 220 221For ISO transfers you have to fill a usb_iso_packet_descriptor structure, 222allocated at the end of the URB by usb_alloc_urb(n,mem_flags), for each 223packet you want to schedule. You also have to set urb->interval to say 224how often to make transfers; it's often one per frame (which is once 225every microframe for highspeed devices). The actual interval used will 226be a power of two that's no bigger than what you specify. 227 228The usb_submit_urb() call modifies urb->interval to the implemented interval 229value that is less than or equal to the requested interval value. If 230ISO_ASAP scheduling is used, urb->start_frame is also updated. 231 232For each entry you have to specify the data offset for this frame (base is 233transfer_buffer), and the length you want to write/expect to read. 234After completion, actual_length contains the actual transferred length and 235status contains the resulting status for the ISO transfer for this frame. 236It is allowed to specify a varying length from frame to frame (e.g. for 237audio synchronisation/adaptive transfer rates). You can also use the length 2380 to omit one or more frames (striping). 239 240For scheduling you can choose your own start frame or ISO_ASAP. As explained 241earlier, if you always keep at least one URB queued and your completion 242keeps (re)submitting a later URB, you'll get smooth ISO streaming (if usb 243bandwidth utilization allows). 244 245If you specify your own start frame, make sure it's several frames in advance 246of the current frame. You might want this model if you're synchronizing 247ISO data with some other event stream. 248 249 2501.9. How to start interrupt (INT) transfers? 251 252Interrupt transfers, like isochronous transfers, are periodic, and happen 253in intervals that are powers of two (1, 2, 4 etc) units. Units are frames 254for full and low speed devices, and microframes for high speed ones. 255The usb_submit_urb() call modifies urb->interval to the implemented interval 256value that is less than or equal to the requested interval value. 257 258In Linux 2.6, unlike earlier versions, interrupt URBs are not automagically 259restarted when they complete. They end when the completion handler is 260called, just like other URBs. If you want an interrupt URB to be restarted, 261your completion handler must resubmit it. 262