1Revised: 2000-Dec-05. 2 31. Specification of the API 4 51.1. Basic concept or 'What is an URB?' 6 7The basic idea of the new driver is message passing, the message itself is 8called USB Request Block, or URB for short. 9 10- An URB consists of all relevant information to execute any USB transaction 11and deliver the data and status back. 12 13- Execution of an URB is inherently an asynchronous operation, i.e. the 14usb_submit_urb(urb) call returns immediately after it has successfully queued 15the requested action. 16 17- Ongoing transfers for one URB (e.g. ISO) can simply be canceled with 18usb_unlink_urb(urb) at any time. 19 20- Each URB has a completion handler, which is called after the action 21has been successfully completed or canceled (INT transfers behave a bit 22differently, see below). The URB also contains a context-pointer for free 23usage and information passing to the completion handler. 24 25- URBs can be linked. After completing one URB, the next one can be 26automatically submitted. This is especially useful for ISO transfers: 27You only have read/write the data from/to the buffers in the completion 28handler, the continuous streaming itself is transparently done by the 29URB-machinery. 30 31 321.2. The URB structure 33 34typedef 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 771.3. How to get an URB? 78 79URBs are allocated with the following call 80 81 purb_t usb_alloc_urb(int isoframes) 82 83Return value is a pointer to the allocated URB, 0 if allocation failed. 84The parameter isoframes specifies the number of isochronous transfer frames 85you want to schedule. For CTRL/BULK/INT, use 0. 86 87To free an URB, use 88 89 void usb_free_urb(purb_t purb) 90 91This call also may free internal (host controller specific) memory in the 92future. 93 94 951.4. What has to be filled in? 96 97Depending on the type of transaction, there are some macros 98(FILL_CONTROL_URB, FILL_CONTROL_URB_TO, FILL_BULK_URB, 99FILL_BULK_URB_TO, and FILL_INT_URB, defined in usb.h) 100that simplify the URB creation. In general, all macros need the usb 101device pointer, the pipe (usual format from usb.h), the transfer buffer, 102the desired transfer length, the completion handler, and its context. 103Take a look at the usb_control_msg function that converts the old API 104into the URB API. 105 106Flags: 107For ISO there are two startup behaviors: Specified start_frame or ASAP. 108For ASAP set USB_ISO_ASAP in transfer_flags. 109 110If short packets should NOT be tolerated, set USB_DISABLE_SPD in 111transfer_flags. 112 113Usually, to reduce restart time, the completion handler is called 114AFTER the URB re-submission. However, it is called BEFORE URB 115re-submission for INT transfers that are being continued. 116 117 1181.5. How to submit an URB? 119 120Just call 121 122 int usb_submit_urb(purb_t purb) 123 124It immediately returns, either with status 0 (request queued) or some 125error 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 136After submission, urb->status is USB_ST_URB_PENDING (-EINPROGRESS). 137 138For isochronous endpoints, subsequent submitting of URBs to the same endpoint 139with the ASAP flag result in a seamless ISO streaming. Exception: The 140execution cannot be scheduled later than 900 frames from the 'now'-time. 141The same applies to INT transfers, but here the seamless continuation is 142independent of the transfer flags (implicitly ASAP). 143 144 1451.6. How to cancel an already running URB? 146 147For an URB which you've submitted, but which hasn't been returned to 148your driver by the host controller, call 149 150 int usb_unlink_urb(purb_t purb) 151 152It removes the urb from the internal list and frees all allocated 153HW descriptors. The status is changed to USB_ST_URB_KILLED. After 154usb_unlink_urb() returns, you can safely free the URB with usb_free_urb(urb) 155and all other possibly associated data (urb->context etc.) 156 157There is also an asynchronous unlink mode. To use this, set the 158the USB_ASYNC_UNLINK flag in urb->transfer flags before calling 159usb_unlink_urb(). When using async unlinking, the URB will not 160normally be unlinked when usb_unlink_urb() returns. Instead, wait 161for the completion handler to be called. 162 163 1641.7. What about the completion handler? 165 166The completion handler is optional, but useful for fast data processing 167or wakeup of a sleeping process (as shown in the compatibility wrapper's 168completion handler). 169 170The handler is of the following type: 171 172 typedef void (*usb_complete_t)(struct urb *); 173 174i.e. it gets just the URB that caused the completion call. 175In the completion handler, you should have a look at urb->status to 176detect any USB errors. Since the context parameter is included in the URB, 177you can pass information to the completion handler. 178 179NOTE: ***** WARNING ***** 180AVOID using the urb->dev field in your completion handler; it's cleared 181as part of URB unlinking. Instead, use urb->context to hold all the 182data your driver needs. 183 184NOTE: ***** WARNING ***** 185Also, NEVER SLEEP IN A COMPLETION HANDLER. These are normally called 186during hardware interrupt processing. If you can, defer substantial 187work to a tasklet (bottom half) to keep system latencies low. You'll 188probably need to use spinlocks to protect data structures you manipulate 189in completion handlers. 190 191 1921.8. How to do isochronous (ISO) transfers? 193 194For ISO transfers you have to append the iso_packet_descriptor_t structure 195to 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 197structures for iso_packets frames. 198 199For each entry you have to specify the data offset for this frame (base is 200transfer_buffer), and the length you want to write/expect to read. 201After completion, actual_length contains the actual transferred length and 202status contains the resulting USB-status for the ISO transfer for this frame. 203It is allowed to specify a varying length from frame to frame (e.g. for 204audio synchronisation/adaptive transfer rates). You can also use the length 2050 to omit one or more frames (striping). 206 207As can be concluded from above, the UHCI-driver does not care for continuous 208data in case of short packet ISO reads! There's no fixup_isoc() like in the 209old driver. There may be a common routine to do this in the future, but this 210has nothing to do with the UHCI-driver! 211 212For scheduling you can choose your own start frame or ASAP. As written above, 213queuing more than one ISO frame with ASAP to the same device&endpoint result 214in seamless ISO streaming. For continuous streaming you have to use URB 215linking. 216 217 2181.9. How to start interrupt (INT) transfers? 219 220INT transfers are currently implemented with different queues for intervals 221for 1, 2, 4,... 128ms. Only one URB is allocated for each interrupt. After 222calling the completion handler, that URB is recycled by the host controller 223driver (HCD). 224With the submission of one URB, the interrupt is scheduled until it is 225canceled by usb_unlink_urb. 226 227The usb_submit_urb() call modifies urb->interval to the implemented interval 228value that is less than or equal to the requested interval value. 229