blob: a49e5f2c2b46e6a2f9947956d17d3a78e045e758 [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001Revised: 2000-Dec-05.
2Again: 2002-Jul-06
Alan Stern0fc084e2005-09-22 00:49:51 -07003Again: 2005-Sep-19
Linus Torvalds1da177e2005-04-16 15:20:36 -07004
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
131.1. Basic concept or 'What is an URB?'
14
15The basic idea of the new driver is message passing, the message itself is
16called 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
Alan Stern0fc084e2005-09-22 00:49:51 -070022 usb_submit_urb(urb) call returns immediately after it has successfully
23 queued the requested action.
Linus Torvalds1da177e2005-04-16 15:20:36 -070024
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
381.2. The URB structure
39
40Some of the fields in an URB are:
41
42struct 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
78Your driver must create the "pipe" value using values from the appropriate
79endpoint descriptor in an interface that it's claimed.
80
81
821.3. How to get an URB?
83
84URBs are allocated with the following call
85
86 struct urb *usb_alloc_urb(int isoframes, int mem_flags)
87
88Return value is a pointer to the allocated URB, 0 if allocation failed.
89The parameter isoframes specifies the number of isochronous transfer frames
90you want to schedule. For CTRL/BULK/INT, use 0. The mem_flags parameter
91holds standard memory allocation flags, letting you control (among other
92things) whether the underlying code may block or not.
93
94To free an URB, use
95
96 void usb_free_urb(struct urb *urb)
97
Alan Stern0fc084e2005-09-22 00:49:51 -070098You may free an urb that you've submitted, but which hasn't yet been
99returned to you in a completion callback. It will automatically be
100deallocated when it is no longer in use.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700101
102
1031.4. What has to be filled in?
104
105Depending on the type of transaction, there are some inline functions
106defined in <linux/usb.h> to simplify the initialization, such as
107fill_control_urb() and fill_bulk_urb(). In general, they need the usb
108device pointer, the pipe (usual format from usb.h), the transfer buffer,
109the desired transfer length, the completion handler, and its context.
110Take a look at the some existing drivers to see how they're used.
111
112Flags:
113For ISO there are two startup behaviors: Specified start_frame or ASAP.
114For ASAP set URB_ISO_ASAP in transfer_flags.
115
116If short packets should NOT be tolerated, set URB_SHORT_NOT_OK in
117transfer_flags.
118
119
1201.5. How to submit an URB?
121
122Just call
123
124 int usb_submit_urb(struct urb *urb, int mem_flags)
125
126The mem_flags parameter, such as SLAB_ATOMIC, controls memory allocation,
127such as whether the lower levels may block when memory is tight.
128
129It immediately returns, either with status 0 (request queued) or some
130error 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
140After submission, urb->status is -EINPROGRESS; however, you should never
141look at that value except in your completion callback.
142
143For isochronous endpoints, your completion handlers should (re)submit
144URBs to the same endpoint with the ISO_ASAP flag, using multi-buffering,
145to get seamless ISO streaming.
146
147
1481.6. How to cancel an already running URB?
149
Alan Stern0fc084e2005-09-22 00:49:51 -0700150There are two ways to cancel an URB you've submitted but which hasn't
151been returned to your driver yet. For an asynchronous cancel, call
Linus Torvalds1da177e2005-04-16 15:20:36 -0700152
153 int usb_unlink_urb(struct urb *urb)
154
155It removes the urb from the internal list and frees all allocated
Alan Stern0fc084e2005-09-22 00:49:51 -0700156HW descriptors. The status is changed to reflect unlinking. Note
157that the URB will not normally have finished when usb_unlink_urb()
158returns; you must still wait for the completion handler to be called.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700159
Alan Stern0fc084e2005-09-22 00:49:51 -0700160To cancel an URB synchronously, call
161
162 void usb_kill_urb(struct urb *urb)
163
164It does everything usb_unlink_urb does, and in addition it waits
165until after the URB has been returned and the completion handler
166has finished. It also marks the URB as temporarily unusable, so
167that if the completion handler or anyone else tries to resubmit it
168they will get a -EPERM error. Thus you can be sure that when
169usb_kill_urb() returns, the URB is totally idle.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700170
171
1721.7. What about the completion handler?
173
174The handler is of the following type:
175
Alan Stern0fc084e2005-09-22 00:49:51 -0700176 typedef void (*usb_complete_t)(struct urb *, struct pt_regs *)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700177
Alan Stern0fc084e2005-09-22 00:49:51 -0700178I.e., it gets the URB that caused the completion call, plus the
179register values at the time of the corresponding interrupt (if any).
Linus Torvalds1da177e2005-04-16 15:20:36 -0700180In the completion handler, you should have a look at urb->status to
181detect any USB errors. Since the context parameter is included in the URB,
182you can pass information to the completion handler.
183
184Note that even when an error (or unlink) is reported, data may have been
185transferred. That's because USB transfers are packetized; it might take
186sixteen packets to transfer your 1KByte buffer, and ten of them might
Alan Stern0fc084e2005-09-22 00:49:51 -0700187have transferred succesfully before the completion was called.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700188
189
190NOTE: ***** WARNING *****
Alan Stern0fc084e2005-09-22 00:49:51 -0700191NEVER SLEEP IN A COMPLETION HANDLER. These are normally called
Linus Torvalds1da177e2005-04-16 15:20:36 -0700192during hardware interrupt processing. If you can, defer substantial
193work to a tasklet (bottom half) to keep system latencies low. You'll
194probably need to use spinlocks to protect data structures you manipulate
195in completion handlers.
196
197
1981.8. How to do isochronous (ISO) transfers?
199
200For ISO transfers you have to fill a usb_iso_packet_descriptor structure,
201allocated at the end of the URB by usb_alloc_urb(n,mem_flags), for each
202packet you want to schedule. You also have to set urb->interval to say
203how often to make transfers; it's often one per frame (which is once
204every microframe for highspeed devices). The actual interval used will
205be a power of two that's no bigger than what you specify.
206
207The usb_submit_urb() call modifies urb->interval to the implemented interval
208value that is less than or equal to the requested interval value. If
209ISO_ASAP scheduling is used, urb->start_frame is also updated.
210
211For each entry you have to specify the data offset for this frame (base is
212transfer_buffer), and the length you want to write/expect to read.
213After completion, actual_length contains the actual transferred length and
214status contains the resulting status for the ISO transfer for this frame.
215It is allowed to specify a varying length from frame to frame (e.g. for
216audio synchronisation/adaptive transfer rates). You can also use the length
2170 to omit one or more frames (striping).
218
219For scheduling you can choose your own start frame or ISO_ASAP. As explained
220earlier, if you always keep at least one URB queued and your completion
221keeps (re)submitting a later URB, you'll get smooth ISO streaming (if usb
222bandwidth utilization allows).
223
224If you specify your own start frame, make sure it's several frames in advance
225of the current frame. You might want this model if you're synchronizing
226ISO data with some other event stream.
227
228
2291.9. How to start interrupt (INT) transfers?
230
231Interrupt transfers, like isochronous transfers, are periodic, and happen
232in intervals that are powers of two (1, 2, 4 etc) units. Units are frames
233for full and low speed devices, and microframes for high speed ones.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700234The usb_submit_urb() call modifies urb->interval to the implemented interval
235value that is less than or equal to the requested interval value.
Alan Stern0fc084e2005-09-22 00:49:51 -0700236
237In Linux 2.6, unlike earlier versions, interrupt URBs are not automagically
238restarted when they complete. They end when the completion handler is
239called, just like other URBs. If you want an interrupt URB to be restarted,
240your completion handler must resubmit it.