Documentation/driver-api/usb/URB.rst

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