Documentation/usb/URB.txt

   1 Revised: 2000-Dec-05.
   2 Again:   2002-Jul-06
   3 Again:   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
  13 1.1. Basic concept or 'What is an URB?'
  14
  15 The basic idea of the new driver is message passing, the message itself is
  16 called 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
  38 1.2. The URB structure
  39
  40 Some of the fields in an URB are:
  41
  42 struct 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
  78 Your driver must create the "pipe" value using values from the appropriate
  79 endpoint descriptor in an interface that it's claimed.
  80
  81
  82 1.3. How to get an URB?
  83
  84 URBs are allocated with the following call
  85
  86         struct urb *usb_alloc_urb(int isoframes, int mem_flags)
  87
  88 Return value is a pointer to the allocated URB, 0 if allocation failed.
  89 The parameter isoframes specifies the number of isochronous transfer frames
  90 you want to schedule. For CTRL/BULK/INT, use 0.  The mem_flags parameter
  91 holds standard memory allocation flags, letting you control (among other
  92 things) whether the underlying code may block or not.
  93
  94 To free an URB, use
  95
  96         void usb_free_urb(struct urb *urb)
  97
  98 You may free an urb that you've submitted, but which hasn't yet been
  99 returned to you in a completion callback.  It will automatically be
 100 deallocated when it is no longer in use.
 101
 102
 103 1.4. What has to be filled in?
 104
 105 Depending on the type of transaction, there are some inline functions
 106 defined in <linux/usb.h> to simplify the initialization, such as
 107 fill_control_urb() and fill_bulk_urb().  In general, they need the usb
 108 device pointer, the pipe (usual format from usb.h), the transfer buffer,
 109 the desired transfer length, the completion  handler, and its context.
 110 Take a look at the some existing drivers to see how they're used.
 111
 112 Flags:
 113 For ISO there are two startup behaviors: Specified start_frame or ASAP.
 114 For ASAP set URB_ISO_ASAP in transfer_flags.
 115
 116 If short packets should NOT be tolerated, set URB_SHORT_NOT_OK in
 117 transfer_flags.
 118
 119
 120 1.5. How to submit an URB?
 121
 122 Just call
 123
 124         int usb_submit_urb(struct urb *urb, int mem_flags)
 125
 126 The mem_flags parameter, such as SLAB_ATOMIC, controls memory allocation,
 127 such as whether the lower levels may block when memory is tight.
 128
 129 It immediately returns, either with status 0 (request queued) or some
 130 error 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
 140 After submission, urb->status is -EINPROGRESS; however, you should never
 141 look at that value except in your completion callback.
 142
 143 For isochronous endpoints, your completion handlers should (re)submit
 144 URBs to the same endpoint with the ISO_ASAP flag, using multi-buffering,
 145 to get seamless ISO streaming.
 146
 147
 148 1.6. How to cancel an already running URB?
 149
 150 There are two ways to cancel an URB you've submitted but which hasn't
 151 been returned to your driver yet.  For an asynchronous cancel, call
 152
 153         int usb_unlink_urb(struct urb *urb)
 154
 155 It removes the urb from the internal list and frees all allocated
 156 HW descriptors. The status is changed to reflect unlinking.  Note
 157 that the URB will not normally have finished when usb_unlink_urb()
 158 returns; you must still wait for the completion handler to be called.
 159
 160 To cancel an URB synchronously, call
 161
 162         void usb_kill_urb(struct urb *urb)
 163
 164 It does everything usb_unlink_urb does, and in addition it waits
 165 until after the URB has been returned and the completion handler
 166 has finished.  It also marks the URB as temporarily unusable, so
 167 that if the completion handler or anyone else tries to resubmit it
 168 they will get a -EPERM error.  Thus you can be sure that when
 169 usb_kill_urb() returns, the URB is totally idle.
 170
 171 There is a lifetime issue to consider.  An URB may complete at any
 172 time, and the completion handler may free the URB.  If this happens
 173 while usb_unlink_urb or usb_kill_urb is running, it will cause a
 174 memory-access violation.  The driver is responsible for avoiding this,
 175 which often means some sort of lock will be needed to prevent the URB
 176 from being deallocated while it is still in use.
 177
 178 On the other hand, since usb_unlink_urb may end up calling the
 179 completion handler, the handler must not take any lock that is held
 180 when usb_unlink_urb is invoked.  The general solution to this problem
 181 is to increment the URB's reference count while holding the lock, then
 182 drop the lock and call usb_unlink_urb or usb_kill_urb, and then
 183 decrement the URB's reference count.  You increment the reference
 184 count 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
 189 decrement the reference count by calling usb_free_urb.  Of course,
 190 none of this is necessary if there's no danger of the URB being freed
 191 by the completion handler.
 192
 193
 194 1.7. What about the completion handler?
 195
 196 The handler is of the following type:
 197
 198         typedef void (*usb_complete_t)(struct urb *)
 199
 200 I.e., it gets the URB that caused the completion call. In the completion
 201 handler, you should have a look at urb->status to detect any USB errors.
 202 Since the context parameter is included in the URB, you can pass
 203 information to the completion handler.
 204
 205 Note that even when an error (or unlink) is reported, data may have been
 206 transferred.  That's because USB transfers are packetized; it might take
 207 sixteen packets to transfer your 1KByte buffer, and ten of them might
 208 have transferred successfully before the completion was called.
 209
 210
 211 NOTE:  ***** WARNING *****
 212 NEVER SLEEP IN A COMPLETION HANDLER.  These are often called in atomic
 213 context.
 214
 215 In the current kernel, completion handlers run with local interrupts
 216 disabled, but in the future this will be changed, so don't assume that
 217 local IRQs are always disabled inside completion handlers.
 218
 219 1.8. How to do isochronous (ISO) transfers?
 220
 221 For ISO transfers you have to fill a usb_iso_packet_descriptor structure,
 222 allocated at the end of the URB by usb_alloc_urb(n,mem_flags), for each
 223 packet you want to schedule.   You also have to set urb->interval to say
 224 how often to make transfers; it's often one per frame (which is once
 225 every microframe for highspeed devices).  The actual interval used will
 226 be a power of two that's no bigger than what you specify.
 227
 228 The usb_submit_urb() call modifies urb->interval to the implemented interval
 229 value that is less than or equal to the requested interval value.  If
 230 ISO_ASAP scheduling is used, urb->start_frame is also updated.
 231
 232 For each entry you have to specify the data offset for this frame (base is
 233 transfer_buffer), and the length you want to write/expect to read.
 234 After completion, actual_length contains the actual transferred length and
 235 status contains the resulting status for the ISO transfer for this frame.
 236 It is allowed to specify a varying length from frame to frame (e.g. for
 237 audio synchronisation/adaptive transfer rates). You can also use the length
 238 0 to omit one or more frames (striping).
 239
 240 For scheduling you can choose your own start frame or ISO_ASAP. As explained
 241 earlier, if you always keep at least one URB queued and your completion
 242 keeps (re)submitting a later URB, you'll get smooth ISO streaming (if usb
 243 bandwidth utilization allows).
 244
 245 If you specify your own start frame, make sure it's several frames in advance
 246 of the current frame.  You might want this model if you're synchronizing
 247 ISO data with some other event stream.
 248
 249
 250 1.9. How to start interrupt (INT) transfers?
 251
 252 Interrupt transfers, like isochronous transfers, are periodic, and happen
 253 in intervals that are powers of two (1, 2, 4 etc) units.  Units are frames
 254 for full and low speed devices, and microframes for high speed ones.
 255 The usb_submit_urb() call modifies urb->interval to the implemented interval
 256 value that is less than or equal to the requested interval value.
 257
 258 In Linux 2.6, unlike earlier versions, interrupt URBs are not automagically
 259 restarted when they complete.  They end when the completion handler is
 260 called, just like other URBs.  If you want an interrupt URB to be restarted,
 261 your completion handler must resubmit it.