Documentation/usb/URB.txt

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