1 |
1275 |
phoenix |
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 |
|
|
|
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.
|