1.. _usb-urb:
2
3USB 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
20Basic concept or 'What is an URB?'
21==================================
22
23The basic idea of the new driver is message passing, the message itself is
24called 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
47The URB structure
48=================
49
50Some of the fields in struct 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
88Your driver must create the "pipe" value using values from the appropriate
89endpoint descriptor in an interface that it's claimed.
90
91
92How to get an URB?
93==================
94
95URBs are allocated by calling :c:func:`usb_alloc_urb`::
96
97	struct urb *usb_alloc_urb(int isoframes, int mem_flags)
98
99Return value is a pointer to the allocated URB, 0 if allocation failed.
100The parameter isoframes specifies the number of isochronous transfer frames
101you want to schedule. For CTRL/BULK/INT, use 0.  The mem_flags parameter
102holds standard memory allocation flags, letting you control (among other
103things) whether the underlying code may block or not.
104
105To free an URB, use :c:func:`usb_free_urb`::
106
107	void usb_free_urb(struct urb *urb)
108
109You may free an urb that you've submitted, but which hasn't yet been
110returned to you in a completion callback.  It will automatically be
111deallocated when it is no longer in use.
112
113
114What has to be filled in?
115=========================
116
117Depending on the type of transaction, there are some inline functions
118defined 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,
121the pipe (usual format from usb.h), the transfer buffer, the desired transfer
122length, the completion handler, and its context. Take a look at the some
123existing drivers to see how they're used.
124
125Flags:
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
130If short packets should NOT be tolerated, set ``URB_SHORT_NOT_OK`` in
131transfer_flags.
132
133
134How to submit an URB?
135=====================
136
137Just call :c:func:`usb_submit_urb`::
138
139	int usb_submit_urb(struct urb *urb, int mem_flags)
140
141The ``mem_flags`` parameter, such as ``GFP_ATOMIC``, controls memory
142allocation, such as whether the lower levels may block when memory is tight.
143
144It immediately returns, either with status 0 (request queued) or some
145error 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
155After submission, ``urb->status`` is ``-EINPROGRESS``; however, you should
156never look at that value except in your completion callback.
157
158For isochronous endpoints, your completion handlers should (re)submit
159URBs to the same endpoint with the ``URB_ISO_ASAP`` flag, using
160multi-buffering, to get seamless ISO streaming.
161
162
163How to cancel an already running URB?
164=====================================
165
166There are two ways to cancel an URB you've submitted but which hasn't
167been 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
172It removes the urb from the internal list and frees all allocated
173HW descriptors. The status is changed to reflect unlinking.  Note
174that the URB will not normally have finished when :c:func:`usb_unlink_urb`
175returns; you must still wait for the completion handler to be called.
176
177To cancel an URB synchronously, call :c:func:`usb_kill_urb`::
178
179	void usb_kill_urb(struct urb *urb)
180
181It does everything :c:func:`usb_unlink_urb` does, and in addition it waits
182until after the URB has been returned and the completion handler
183has finished.  It also marks the URB as temporarily unusable, so
184that if the completion handler or anyone else tries to resubmit it
185they 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
188There is a lifetime issue to consider.  An URB may complete at any
189time, and the completion handler may free the URB.  If this happens
190while :c:func:`usb_unlink_urb` or :c:func:`usb_kill_urb` is running, it will
191cause a memory-access violation.  The driver is responsible for avoiding this,
192which often means some sort of lock will be needed to prevent the URB
193from being deallocated while it is still in use.
194
195On the other hand, since usb_unlink_urb may end up calling the
196completion handler, the handler must not take any lock that is held
197when usb_unlink_urb is invoked.  The general solution to this problem
198is to increment the URB's reference count while holding the lock, then
199drop the lock and call usb_unlink_urb or usb_kill_urb, and then
200decrement the URB's reference count.  You increment the reference
201count 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
206decrement the reference count by calling :c:func:`usb_free_urb`.  Of course,
207none of this is necessary if there's no danger of the URB being freed
208by the completion handler.
209
210
211What about the completion handler?
212==================================
213
214The handler is of the following type::
215
216	typedef void (*usb_complete_t)(struct urb *)
217
218I.e., it gets the URB that caused the completion call. In the completion
219handler, you should have a look at ``urb->status`` to detect any USB errors.
220Since the context parameter is included in the URB, you can pass
221information to the completion handler.
222
223Note that even when an error (or unlink) is reported, data may have been
224transferred.  That's because USB transfers are packetized; it might take
225sixteen packets to transfer your 1KByte buffer, and ten of them might
226have 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
235In the current kernel, completion handlers run with local interrupts
236disabled, but in the future this will be changed, so don't assume that
237local IRQs are always disabled inside completion handlers.
238
239How to do isochronous (ISO) transfers?
240======================================
241
242Besides the fields present on a bulk transfer, for ISO, you also
243have to set ``urb->interval`` to say how often to make transfers; it's
244often one per frame (which is once every microframe for highspeed devices).
245The actual interval used will be a power of two that's no bigger than what
246you specify. You can use the :c:func:`usb_fill_int_urb` macro to fill
247most ISO transfer fields.
248
249For ISO transfers you also have to fill a :c:type:`usb_iso_packet_descriptor`
250structure, allocated at the end of the URB by :c:func:`usb_alloc_urb`, for
251each packet you want to schedule.
252
253The :c:func:`usb_submit_urb` call modifies ``urb->interval`` to the implemented
254interval 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
257For each entry you have to specify the data offset for this frame (base is
258transfer_buffer), and the length you want to write/expect to read.
259After completion, actual_length contains the actual transferred length and
260status contains the resulting status for the ISO transfer for this frame.
261It is allowed to specify a varying length from frame to frame (e.g. for
262audio synchronisation/adaptive transfer rates). You can also use the length
2630 to omit one or more frames (striping).
264
265For scheduling you can choose your own start frame or ``URB_ISO_ASAP``. As
266explained earlier, if you always keep at least one URB queued and your
267completion keeps (re)submitting a later URB, you'll get smooth ISO streaming
268(if usb bandwidth utilization allows).
269
270If you specify your own start frame, make sure it's several frames in advance
271of the current frame.  You might want this model if you're synchronizing
272ISO data with some other event stream.
273
274
275How to start interrupt (INT) transfers?
276=======================================
277
278Interrupt transfers, like isochronous transfers, are periodic, and happen
279in intervals that are powers of two (1, 2, 4 etc) units.  Units are frames
280for full and low speed devices, and microframes for high speed ones.
281You can use the :c:func:`usb_fill_int_urb` macro to fill INT transfer fields.
282
283The :c:func:`usb_submit_urb` call modifies ``urb->interval`` to the implemented
284interval value that is less than or equal to the requested interval value.
285
286In Linux 2.6, unlike earlier versions, interrupt URBs are not automagically
287restarted when they complete.  They end when the completion handler is
288called, just like other URBs.  If you want an interrupt URB to be restarted,
289your completion handler must resubmit it.
290s
291