driver-api/usb/URB.rst

3 USB Request Block (URB)
20 Basic concept or 'What is an URB?'
24 called USB Request Block, or URB for short.
26 - An URB consists of all relevant information to execute any USB transaction
29 - Execution of an URB is inherently an asynchronous operation, i.e. the
33 - Transfers for one URB can be canceled with :c:func:`usb_unlink_urb`
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
47 The URB structure
92 How to get an URB?
99 Return value is a pointer to the allocated URB, 0 if allocation failed.
105 To free an URB, use :c:func:`usb_free_urb`::
134 How to submit an URB?
163 How to cancel an already running URB?
166 There are two ways to cancel an URB you've submitted but which hasn't
174 that the URB will not normally have finished when :c:func:`usb_unlink_urb`
177 To cancel an URB synchronously, call :c:func:`usb_kill_urb`::
182 until after the URB has been returned and the completion handler
183 has finished.  It also marks the URB as temporarily unusable, so
186 :c:func:`usb_kill_urb` returns, the URB is totally idle.
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
192 which often means some sort of lock will be needed to prevent the URB
198 is to increment the URB's reference count while holding the lock, then
200 decrement the URB's reference count.  You increment the reference
207 none of this is necessary if there's no danger of the URB being freed
218 I.e., it gets the URB that caused the completion call. In the completion
220 Since the context parameter is included in the URB, you can pass
250 structure, allocated at the end of the URB by :c:func:`usb_alloc_urb`, for
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
288 called, just like other URBs.  If you want an interrupt URB to be restarted,