About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / usb / URB.txt


Based on kernel version 4.10.8. Page generated on 2017-04-01 14:44 EST.

1	Revised: 2000-Dec-05.
2	Again:   2002-Jul-06
3	Again:   2005-Sep-19
4	
5	    NOTE:
6	
7	    The USB subsystem now has a substantial section in "The Linux Kernel API"
8	    guide (in Documentation/DocBook), generated from the current source
9	    code.  This particular documentation file isn't particularly current or
10	    complete; don't rely on it except for a quick overview.
11	
12	
13	1.1. Basic concept or 'What is an URB?'
14	
15	The basic idea of the new driver is message passing, the message itself is 
16	called USB Request Block, or URB for short. 
17	
18	- An URB consists of all relevant information to execute any USB transaction 
19	  and deliver the data and status back. 
20	
21	- Execution of an URB is inherently an asynchronous operation, i.e. the 
22	  usb_submit_urb(urb) call returns immediately after it has successfully
23	  queued the requested action.
24	
25	- Transfers for one URB can be canceled with usb_unlink_urb(urb) at any time. 
26	
27	- Each URB has a completion handler, which is called after the action
28	  has been successfully completed or canceled. The URB also contains a
29	  context-pointer for passing information to the completion handler.
30	
31	- Each endpoint for a device logically supports a queue of requests.
32	  You can fill that queue, so that the USB hardware can still transfer
33	  data to an endpoint while your driver handles completion of another.
34	  This maximizes use of USB bandwidth, and supports seamless streaming
35	  of data to (or from) devices when using periodic transfer modes.
36	
37	
38	1.2. The URB structure
39	
40	Some of the fields in an URB are:
41	
42	struct urb
43	{
44	// (IN) device and pipe specify the endpoint queue
45		struct usb_device *dev;         // pointer to associated USB device
46		unsigned int pipe;              // endpoint information
47	
48		unsigned int transfer_flags;    // ISO_ASAP, SHORT_NOT_OK, etc.
49	
50	// (IN) all urbs need completion routines
51		void *context;                  // context for completion routine
52		void (*complete)(struct urb *); // pointer to completion routine
53	
54	// (OUT) status after each completion
55		int status;                     // returned status
56	
57	// (IN) buffer used for data transfers
58		void *transfer_buffer;          // associated data buffer
59		int transfer_buffer_length;     // data buffer length
60		int number_of_packets;          // size of iso_frame_desc
61	
62	// (OUT) sometimes only part of CTRL/BULK/INTR transfer_buffer is used
63		int actual_length;              // actual data buffer length
64	
65	// (IN) setup stage for CTRL (pass a struct usb_ctrlrequest)
66		unsigned char* setup_packet;    // setup packet (control only)
67	
68	// Only for PERIODIC transfers (ISO, INTERRUPT)
69	    // (IN/OUT) start_frame is set unless ISO_ASAP isn't set
70		int start_frame;                // start frame
71		int interval;                   // polling interval
72	
73	    // ISO only: packets are only "best effort"; each can have errors
74		int error_count;                // number of errors
75		struct usb_iso_packet_descriptor iso_frame_desc[0];
76	};
77	
78	Your driver must create the "pipe" value using values from the appropriate
79	endpoint descriptor in an interface that it's claimed.
80	
81	
82	1.3. How to get an URB?
83	
84	URBs are allocated with the following call
85	
86		struct urb *usb_alloc_urb(int isoframes, int mem_flags)
87	
88	Return value is a pointer to the allocated URB, 0 if allocation failed.
89	The parameter isoframes specifies the number of isochronous transfer frames
90	you want to schedule. For CTRL/BULK/INT, use 0.  The mem_flags parameter
91	holds standard memory allocation flags, letting you control (among other
92	things) whether the underlying code may block or not.
93	
94	To free an URB, use
95	
96		void usb_free_urb(struct urb *urb)
97	
98	You may free an urb that you've submitted, but which hasn't yet been
99	returned to you in a completion callback.  It will automatically be
100	deallocated when it is no longer in use.
101	
102	
103	1.4. What has to be filled in?
104	
105	Depending on the type of transaction, there are some inline functions 
106	defined in <linux/usb.h> to simplify the initialization, such as
107	fill_control_urb() and fill_bulk_urb().  In general, they need the usb
108	device pointer, the pipe (usual format from usb.h), the transfer buffer,
109	the desired transfer length, the completion  handler, and its context. 
110	Take a look at the some existing drivers to see how they're used.
111	
112	Flags:
113	For ISO there are two startup behaviors: Specified start_frame or ASAP.
114	For ASAP set URB_ISO_ASAP in transfer_flags.
115	
116	If short packets should NOT be tolerated, set URB_SHORT_NOT_OK in 
117	transfer_flags.
118	
119	
120	1.5. How to submit an URB?
121	
122	Just call
123	
124		int usb_submit_urb(struct urb *urb, int mem_flags)
125	
126	The mem_flags parameter, such as SLAB_ATOMIC, controls memory allocation,
127	such as whether the lower levels may block when memory is tight.
128	
129	It immediately returns, either with status 0 (request queued) or some
130	error code, usually caused by the following:
131	
132	- Out of memory (-ENOMEM)
133	- Unplugged device (-ENODEV)
134	- Stalled endpoint (-EPIPE)
135	- Too many queued ISO transfers (-EAGAIN)
136	- Too many requested ISO frames (-EFBIG)
137	- Invalid INT interval (-EINVAL)
138	- More than one packet for INT (-EINVAL)
139	
140	After submission, urb->status is -EINPROGRESS; however, you should never
141	look at that value except in your completion callback.
142	
143	For isochronous endpoints, your completion handlers should (re)submit
144	URBs to the same endpoint with the ISO_ASAP flag, using multi-buffering,
145	to get seamless ISO streaming.
146	
147	
148	1.6. How to cancel an already running URB?
149	
150	There are two ways to cancel an URB you've submitted but which hasn't
151	been returned to your driver yet.  For an asynchronous cancel, call
152	
153		int usb_unlink_urb(struct urb *urb)
154	
155	It removes the urb from the internal list and frees all allocated
156	HW descriptors. The status is changed to reflect unlinking.  Note
157	that the URB will not normally have finished when usb_unlink_urb()
158	returns; you must still wait for the completion handler to be called.
159	
160	To cancel an URB synchronously, call
161	
162		void usb_kill_urb(struct urb *urb)
163	
164	It does everything usb_unlink_urb does, and in addition it waits
165	until after the URB has been returned and the completion handler
166	has finished.  It also marks the URB as temporarily unusable, so
167	that if the completion handler or anyone else tries to resubmit it
168	they will get a -EPERM error.  Thus you can be sure that when
169	usb_kill_urb() returns, the URB is totally idle.
170	
171	There is a lifetime issue to consider.  An URB may complete at any
172	time, and the completion handler may free the URB.  If this happens
173	while usb_unlink_urb or usb_kill_urb is running, it will cause a
174	memory-access violation.  The driver is responsible for avoiding this,
175	which often means some sort of lock will be needed to prevent the URB
176	from being deallocated while it is still in use.
177	
178	On the other hand, since usb_unlink_urb may end up calling the
179	completion handler, the handler must not take any lock that is held
180	when usb_unlink_urb is invoked.  The general solution to this problem
181	is to increment the URB's reference count while holding the lock, then
182	drop the lock and call usb_unlink_urb or usb_kill_urb, and then
183	decrement the URB's reference count.  You increment the reference
184	count by calling
185	
186		struct urb *usb_get_urb(struct urb *urb)
187	
188	(ignore the return value; it is the same as the argument) and
189	decrement the reference count by calling usb_free_urb.  Of course,
190	none of this is necessary if there's no danger of the URB being freed
191	by the completion handler.
192	
193	
194	1.7. What about the completion handler?
195	
196	The handler is of the following type:
197	
198		typedef void (*usb_complete_t)(struct urb *)
199	
200	I.e., it gets the URB that caused the completion call. In the completion
201	handler, you should have a look at urb->status to detect any USB errors.
202	Since the context parameter is included in the URB, you can pass
203	information to the completion handler.
204	
205	Note that even when an error (or unlink) is reported, data may have been
206	transferred.  That's because USB transfers are packetized; it might take
207	sixteen packets to transfer your 1KByte buffer, and ten of them might
208	have transferred successfully before the completion was called.
209	
210	
211	NOTE:  ***** WARNING *****
212	NEVER SLEEP IN A COMPLETION HANDLER.  These are often called in atomic
213	context.
214	
215	In the current kernel, completion handlers run with local interrupts
216	disabled, but in the future this will be changed, so don't assume that
217	local IRQs are always disabled inside completion handlers.
218	
219	1.8. How to do isochronous (ISO) transfers?
220	
221	For ISO transfers you have to fill a usb_iso_packet_descriptor structure,
222	allocated at the end of the URB by usb_alloc_urb(n,mem_flags), for each
223	packet you want to schedule.   You also have to set urb->interval to say
224	how often to make transfers; it's often one per frame (which is once
225	every microframe for highspeed devices).  The actual interval used will
226	be a power of two that's no bigger than what you specify.
227	
228	The usb_submit_urb() call modifies urb->interval to the implemented interval
229	value that is less than or equal to the requested interval value.  If
230	ISO_ASAP scheduling is used, urb->start_frame is also updated.
231	
232	For each entry you have to specify the data offset for this frame (base is
233	transfer_buffer), and the length you want to write/expect to read.
234	After completion, actual_length contains the actual transferred length and 
235	status contains the resulting status for the ISO transfer for this frame.
236	It is allowed to specify a varying length from frame to frame (e.g. for
237	audio synchronisation/adaptive transfer rates). You can also use the length 
238	0 to omit one or more frames (striping).
239	
240	For scheduling you can choose your own start frame or ISO_ASAP. As explained
241	earlier, if you always keep at least one URB queued and your completion
242	keeps (re)submitting a later URB, you'll get smooth ISO streaming (if usb
243	bandwidth utilization allows).
244	
245	If you specify your own start frame, make sure it's several frames in advance
246	of the current frame.  You might want this model if you're synchronizing
247	ISO data with some other event stream.
248	
249	
250	1.9. How to start interrupt (INT) transfers?
251	
252	Interrupt transfers, like isochronous transfers, are periodic, and happen
253	in intervals that are powers of two (1, 2, 4 etc) units.  Units are frames
254	for full and low speed devices, and microframes for high speed ones.
255	The usb_submit_urb() call modifies urb->interval to the implemented interval
256	value that is less than or equal to the requested interval value.
257	
258	In Linux 2.6, unlike earlier versions, interrupt URBs are not automagically
259	restarted when they complete.  They end when the completion handler is
260	called, just like other URBs.  If you want an interrupt URB to be restarted,
261	your completion handler must resubmit it.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog