/Documentation/usb/URB.txt

https://bitbucket.org/evzijst/gittest · Plain Text · 252 lines · 177 code · 75 blank · 0 comment · 0 complexity · ab01e91e79046e623c9bdaec6c0088d8 MD5 · raw file

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