Documentation/usb/URB.txt

   1 Revised: 2000-Dec-05.
   2
   3 1. Specification of the API
   4
   5 1.1. Basic concept or 'What is an URB?'
   6
   7 The basic idea of the new driver is message passing, the message itself is
   8 called USB Request Block, or URB for short.
   9
  10 - An URB consists of all relevant information to execute any USB transaction
  11 and deliver the data and status back.
  12
  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
  17 - Ongoing transfers for one URB (e.g. ISO) can simply be canceled with
  18 usb_unlink_urb(urb) at any time.
  19
  20 - Each URB has a completion handler, which is called after the action
  21 has been successfully completed or canceled (INT transfers behave a bit
  22 differently, see below). The URB also contains a context-pointer for free
  23 usage and information passing to the completion handler.
  24
  25 - URBs can be linked. After completing one URB, the next one can be
  26 automatically submitted. This is especially useful for ISO transfers:
  27 You only have read/write the data from/to the buffers in the completion
  28 handler, the continuous streaming itself is transparently done by the
  29 URB-machinery.
  30
  31
  32 1.2. The URB structure
  33
  34 typedef struct urb
  35 {
  36         spinlock_t lock;                // lock for the URB
  37
  38 // ignore, for host controller/URB machine internal use
  39         void *hcpriv;                   // private data for host controller
  40         struct list_head urb_list;      // list pointer to all active urbs
  41
  42 // This is used for urb linking
  43         struct urb* next;               // pointer to next URB
  44         struct usb_device *dev;         // pointer to associated USB device
  45
  46 // pipe is assembled by the various well-known pipe macros in usb.h
  47         unsigned int pipe;              // pipe information
  48
  49 // status after each completion
  50         int status;                     // returned status
  51         unsigned int transfer_flags;    // ASAP, DISABLE_SPD, etc.
  52
  53 // for data stage (CTRL), BULK, INT and ISO
  54         void *transfer_buffer;          // associated data buffer
  55
  56 // expected length
  57         int transfer_buffer_length;     // data buffer length
  58         int actual_length;              // actual data buffer length
  59
  60 // setup stage for CTRL (always 8 bytes!)
  61         unsigned char* setup_packet;    // setup packet (control only)
  62
  63 // with ASAP, start_frame is set to the determined frame
  64         int start_frame;                // start frame (iso/irq)
  65         int number_of_packets;          // # of packets (iso/int)
  66         int interval;                   // polling interval (irq only)
  67         int error_count;                // number of errors (iso only)
  68         //
  69         void *context;                  // context for completion routine
  70         usb_complete_t complete;        // pointer to completion routine
  71         //
  72 // specification of the requested data offsets and length for ISO
  73         iso_packet_descriptor_t iso_frame_desc[0];
  74 } urb_t, *purb_t;
  75
  76
  77 1.3. How to get an URB?
  78
  79 URBs are allocated with the following call
  80
  81         purb_t usb_alloc_urb(int isoframes)
  82
  83 Return value is a pointer to the allocated URB, 0 if allocation failed.
  84 The parameter isoframes specifies the number of isochronous transfer frames
  85 you want to schedule. For CTRL/BULK/INT, use 0.
  86
  87 To free an URB, use
  88
  89         void usb_free_urb(purb_t purb)
  90
  91 This call also may free internal (host controller specific) memory in the
  92 future.
  93
  94
  95 1.4. What has to be filled in?
  96
  97 Depending on the type of transaction, there are some macros
  98 (FILL_CONTROL_URB, FILL_CONTROL_URB_TO, FILL_BULK_URB,
  99 FILL_BULK_URB_TO, and FILL_INT_URB, defined in usb.h)
 100 that simplify the URB creation. In general, all macros need the usb
 101 device pointer, the pipe (usual format from usb.h), the transfer buffer,
 102 the desired transfer length, the completion  handler, and its context.
 103 Take a look at the usb_control_msg function that converts the old API
 104 into the URB API.
 105
 106 Flags:
 107 For ISO there are two startup behaviors: Specified start_frame or ASAP.
 108 For ASAP set USB_ISO_ASAP in transfer_flags.
 109
 110 If short packets should NOT be tolerated, set USB_DISABLE_SPD in
 111 transfer_flags.
 112
 113 Usually, to reduce restart time, the completion handler is called
 114 AFTER the URB re-submission.  However, it is called BEFORE URB
 115 re-submission for INT transfers that are being continued.
 116
 117
 118 1.5. How to submit an URB?
 119
 120 Just call
 121
 122         int usb_submit_urb(purb_t purb)
 123
 124 It immediately returns, either with status 0 (request queued) or some
 125 error code, usually caused by the following:
 126
 127 - Out of memory (-ENOMEM)
 128 - Wrong pipe handle (-ENXIO)
 129 - Unplugged device (-ENODEV)
 130 - Stalled endpoint (-EPIPE)
 131 - Too many queued ISO transfers (-EAGAIN)
 132 - Too many requested ISO frames (-EFBIG)
 133 - Invalid INT interval (-EINVAL)
 134 - More than one packet for INT (-EINVAL)
 135
 136 After submission, urb->status is USB_ST_URB_PENDING (-EINPROGRESS).
 137
 138 For isochronous endpoints, subsequent submitting of URBs to the same endpoint
 139 with the ASAP flag result in a seamless ISO streaming. Exception: The
 140 execution cannot be scheduled later than 900 frames from the 'now'-time.
 141 The same applies to INT transfers, but here the seamless continuation is
 142 independent of the transfer flags (implicitly ASAP).
 143
 144
 145 1.6. How to cancel an already running URB?
 146
 147 For an URB which you've submitted, but which hasn't been returned to
 148 your driver by the host controller, call
 149
 150         int usb_unlink_urb(purb_t purb)
 151
 152 It removes the urb from the internal list and frees all allocated
 153 HW descriptors. The status is changed to USB_ST_URB_KILLED. After
 154 usb_unlink_urb() returns, you can safely free the URB with usb_free_urb(urb)
 155 and all other possibly associated data (urb->context etc.)
 156
 157 There is also an asynchronous unlink mode.  To use this, set the
 158 the USB_ASYNC_UNLINK flag in urb->transfer flags before calling
 159 usb_unlink_urb().  When using async unlinking, the URB will not
 160 normally be unlinked when usb_unlink_urb() returns.  Instead, wait
 161 for the completion handler to be called.
 162
 163
 164 1.7. What about the completion handler?
 165
 166 The completion handler is optional, but useful for fast data processing
 167 or wakeup of a sleeping process (as shown in the compatibility wrapper's
 168 completion handler).
 169
 170 The handler is of the following type:
 171
 172         typedef void (*usb_complete_t)(struct urb *);
 173
 174 i.e. it gets just the URB that caused the completion call.
 175 In the completion handler, you should have a look at urb->status to
 176 detect any USB errors. Since the context parameter is included in the URB,
 177 you can pass information to the completion handler.
 178
 179 NOTE:  ***** WARNING *****
 180 AVOID using the urb->dev field in your completion handler; it's cleared
 181 as part of URB unlinking.  Instead, use urb->context to hold all the
 182 data your driver needs.
 183
 184 NOTE:  ***** WARNING *****
 185 Also, NEVER SLEEP IN A COMPLETION HANDLER.  These are normally called
 186 during hardware interrupt processing.  If you can, defer substantial
 187 work to a tasklet (bottom half) to keep system latencies low.  You'll
 188 probably need to use spinlocks to protect data structures you manipulate
 189 in completion handlers.
 190
 191
 192 1.8. How to do isochronous (ISO) transfers?
 193
 194 For ISO transfers you have to append the iso_packet_descriptor_t structure
 195 to the URB for each frame you want to schedule. When using usb_alloc_urb(n)
 196 (recommended), the iso_packets parameter can be used to allocate the
 197 structures for iso_packets frames.
 198
 199 For each entry you have to specify the data offset for this frame (base is
 200 transfer_buffer), and the length you want to write/expect to read.
 201 After completion, actual_length contains the actual transferred length and
 202 status contains the resulting USB-status for the ISO transfer for this frame.
 203 It is allowed to specify a varying length from frame to frame (e.g. for
 204 audio synchronisation/adaptive transfer rates). You can also use the length
 205 0 to omit one or more frames (striping).
 206
 207 As can be concluded from above, the UHCI-driver does not care for continuous
 208 data in case of short packet ISO reads! There's no fixup_isoc() like in the
 209 old driver. There may be a common routine to do this in the future, but this
 210 has nothing to do with the UHCI-driver!
 211
 212 For scheduling you can choose your own start frame or ASAP. As written above,
 213 queuing more than one ISO frame with ASAP to the same device&endpoint result
 214 in seamless ISO streaming. For continuous streaming you have to use URB
 215 linking.
 216
 217
 218 1.9. How to start interrupt (INT) transfers?
 219
 220 INT transfers are currently implemented with different queues for intervals
 221 for 1, 2, 4,... 128ms. Only one URB is allocated for each interrupt. After
 222 calling the completion handler, that URB is recycled by the host controller
 223 driver (HCD).
 224 With the submission of one URB, the interrupt is scheduled until it is
 225 canceled by usb_unlink_urb.
 226
 227 The usb_submit_urb() call modifies urb->interval to the implemented interval
 228 value that is less than or equal to the requested interval value.