/Documentation/usb/URB.txt

  1Revised: 2000-Dec-05.
  2Again:   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
 121.1. Basic concept or 'What is an URB?'
 13
 14The basic idea of the new driver is message passing, the message itself is 
 15called 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
 371.2. The URB structure
 38
 39Some of the fields in an URB are:
 40
 41struct 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
 77Your driver must create the "pipe" value using values from the appropriate
 78endpoint descriptor in an interface that it's claimed.
 79
 80
 811.3. How to get an URB?
 82
 83URBs are allocated with the following call
 84
 85	struct urb *usb_alloc_urb(int isoframes, int mem_flags)
 86
 87Return value is a pointer to the allocated URB, 0 if allocation failed.
 88The parameter isoframes specifies the number of isochronous transfer frames
 89you want to schedule. For CTRL/BULK/INT, use 0.  The mem_flags parameter
 90holds standard memory allocation flags, letting you control (among other
 91things) whether the underlying code may block or not.
 92
 93To free an URB, use
 94
 95	void usb_free_urb(struct urb *urb)
 96
 97You may not free an urb that you've submitted, but which hasn't yet been
 98returned to you in a completion callback.
 99
100
1011.4. What has to be filled in?
102
103Depending on the type of transaction, there are some inline functions 
104defined in <linux/usb.h> to simplify the initialization, such as
105fill_control_urb() and fill_bulk_urb().  In general, they need the usb
106device pointer, the pipe (usual format from usb.h), the transfer buffer,
107the desired transfer length, the completion  handler, and its context. 
108Take a look at the some existing drivers to see how they're used.
109
110Flags:
111For ISO there are two startup behaviors: Specified start_frame or ASAP.
112For ASAP set URB_ISO_ASAP in transfer_flags.
113
114If short packets should NOT be tolerated, set URB_SHORT_NOT_OK in 
115transfer_flags.
116
117
1181.5. How to submit an URB?
119
120Just call
121
122	int usb_submit_urb(struct urb *urb, int mem_flags)
123
124The mem_flags parameter, such as SLAB_ATOMIC, controls memory allocation,
125such as whether the lower levels may block when memory is tight.
126
127It immediately returns, either with status 0 (request queued) or some
128error 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
138After submission, urb->status is -EINPROGRESS; however, you should never
139look at that value except in your completion callback.
140
141For isochronous endpoints, your completion handlers should (re)submit
142URBs to the same endpoint with the ISO_ASAP flag, using multi-buffering,
143to get seamless ISO streaming.
144
145
1461.6. How to cancel an already running URB?
147
148For an URB which you've submitted, but which hasn't been returned to
149your driver by the host controller, call
150
151	int usb_unlink_urb(struct urb *urb)
152
153It removes the urb from the internal list and frees all allocated
154HW descriptors. The status is changed to reflect unlinking. After 
155usb_unlink_urb() returns with that status code, you can free the URB
156with usb_free_urb().
157
158There is also an asynchronous unlink mode.  To use this, set the
159the URB_ASYNC_UNLINK flag in urb->transfer flags before calling
160usb_unlink_urb().  When using async unlinking, the URB will not
161normally be unlinked when usb_unlink_urb() returns.  Instead, wait
162for the completion handler to be called.
163
164
1651.7. What about the completion handler?
166
167The handler is of the following type:
168
169	typedef void (*usb_complete_t)(struct urb *);
170
171i.e. it gets just the URB that caused the completion call.
172In the completion handler, you should have a look at urb->status to
173detect any USB errors. Since the context parameter is included in the URB,
174you can pass information to the completion handler. 
175
176Note that even when an error (or unlink) is reported, data may have been
177transferred.  That's because USB transfers are packetized; it might take
178sixteen packets to transfer your 1KByte buffer, and ten of them might
179have transferred succesfully before the completion is called.
180
181
182NOTE:  ***** WARNING *****
183Don't use urb->dev field in your completion handler; it's cleared
184as part of giving urbs back to drivers.  (Addressing an issue with
185ownership of periodic URBs, which was otherwise ambiguous.) Instead,
186use urb->context to hold all the data your driver needs.
187
188NOTE:  ***** WARNING *****
189Also, NEVER SLEEP IN A COMPLETION HANDLER.  These are normally called
190during hardware interrupt processing.  If you can, defer substantial
191work to a tasklet (bottom half) to keep system latencies low.  You'll
192probably need to use spinlocks to protect data structures you manipulate
193in completion handlers.
194
195
1961.8. How to do isochronous (ISO) transfers?
197
198For ISO transfers you have to fill a usb_iso_packet_descriptor structure,
199allocated at the end of the URB by usb_alloc_urb(n,mem_flags), for each
200packet you want to schedule.   You also have to set urb->interval to say
201how often to make transfers; it's often one per frame (which is once
202every microframe for highspeed devices).  The actual interval used will
203be a power of two that's no bigger than what you specify.
204
205The usb_submit_urb() call modifies urb->interval to the implemented interval
206value that is less than or equal to the requested interval value.  If
207ISO_ASAP scheduling is used, urb->start_frame is also updated.
208
209For each entry you have to specify the data offset for this frame (base is
210transfer_buffer), and the length you want to write/expect to read.
211After completion, actual_length contains the actual transferred length and 
212status contains the resulting status for the ISO transfer for this frame.
213It is allowed to specify a varying length from frame to frame (e.g. for
214audio synchronisation/adaptive transfer rates). You can also use the length 
2150 to omit one or more frames (striping).
216
217For scheduling you can choose your own start frame or ISO_ASAP. As explained
218earlier, if you always keep at least one URB queued and your completion
219keeps (re)submitting a later URB, you'll get smooth ISO streaming (if usb
220bandwidth utilization allows).
221
222If you specify your own start frame, make sure it's several frames in advance
223of the current frame.  You might want this model if you're synchronizing
224ISO data with some other event stream.
225
226
2271.9. How to start interrupt (INT) transfers?
228
229Interrupt transfers, like isochronous transfers, are periodic, and happen
230in intervals that are powers of two (1, 2, 4 etc) units.  Units are frames
231for full and low speed devices, and microframes for high speed ones.
232
233Currently, after you submit one interrupt URB, that urb is owned by the
234host controller driver until you cancel it with usb_unlink_urb().  You
235may unlink interrupt urbs in their completion handlers, if you need to.
236
237After a transfer completion is called, the URB is automagically resubmitted.
238THIS BEHAVIOR IS EXPECTED TO BE REMOVED!!
239
240Interrupt transfers may only send (or receive) the "maxpacket" value for
241the given interrupt endpoint; if you need more data, you will need to
242copy that data out of (or into) another buffer.  Similarly, you can't
243queue interrupt transfers.
244THESE RESTRICTIONS ARE EXPECTED TO BE REMOVED!!
245
246Note that this automagic resubmission model does make it awkward to use
247interrupt OUT transfers.  The portable solution involves unlinking those
248OUT urbs after the data is transferred, and perhaps submitting a final
249URB for a short packet.
250
251The usb_submit_urb() call modifies urb->interval to the implemented interval
252value that is less than or equal to the requested interval value.