patch-2.4.0-test9 linux/Documentation/usb/URB.txt

• Lines: 112
• Date: Tue Oct 3 09:24:40 2000
• Orig file: v2.4.0-test8/linux/Documentation/usb/URB.txt
• Orig date: Fri Jul 28 12:50:52 2000

diff -u --recursive --new-file v2.4.0-test8/linux/Documentation/usb/URB.txt linux/Documentation/usb/URB.txt
@@ -26,6 +26,7 @@
 handler, the continuous streaming itself is transparently done by the 
 URB-machinery.
 
+
 1.2. The URB structure
 
 typedef struct urb
@@ -43,7 +44,7 @@
 
 // status after each completion
 	int status;                     // returned status
-	unsigned int transfer_flags;    // ASAP, SP_OK, EARLY_COMPLETE
+	unsigned int transfer_flags;    // ASAP, SP_OK, etc.
 
 // for data stage (CTRL), BULK, INT and ISO
 	void *transfer_buffer;          // associated data buffer
@@ -68,6 +69,7 @@
 	iso_packet_descriptor_t  iso_frame_desc[0];
 } urb_t, *purb_t;
 
+
 1.3. How to get an URB?
 
 URBs are allocated with the following call
@@ -85,6 +87,7 @@
 This call also may free internal (host controller specific) memory in the
 future.
 
+
 1.4. What has to be filled in?
 
 Depending on the type of transaction, there are some macros 
@@ -102,10 +105,10 @@
 If short packets should NOT be tolerated, set USB_DISABLE_SPD in 
 transfer_flags.
 
-Usually, (to reduce restart time) the completion handler is called
-AFTER the URB re-submission. You can get the other way by setting
-USB_URB_EARLY_COMPLETE in transfer_flags. This is implicit for
-INT transfers.
+Usually, to reduce restart time, the completion handler is called
+AFTER the URB re-submission.  However, it is called BEFORE URB
+re-submission for INT transfers that are being continued.
+
 
 1.5. How to submit an URB?
 
@@ -133,9 +136,12 @@
 The same applies to INT transfers, but here the seamless continuation is 
 independent of the transfer flags (implicitly ASAP).
 
+
 1.6. How to cancel an already running URB?
 
-Call
+For an URB which you've submitted, but which hasn't been returned to
+your driver by the host controller, call
+
 	int unlink_urb(purb_t purb)
 
 It removes the urb from the internal list and frees all allocated
@@ -143,6 +149,13 @@
 unlink_urb() returns, you can safely free the URB with free_urb(urb)
 and all other possibly associated data (urb->context etc.)
 
+There is also an asynchronous unlink mode.  To use this, set the
+the USB_ASYNC_UNLINK flag in urb->transfer flags before calling
+usb_unlink_urb().  When using async unlinking, the URB will not
+normally be unlinked when unlink_urb() returns.  Instead, wait for
+the completion handler to be called.
+
+
 1.7. What about the completion handler?
 
 The completion handler is optional, but useful for fast data processing
@@ -158,6 +171,18 @@
 detect any USB errors. Since the context parameter is included in the URB,
 you can pass information to the completion handler. 
 
+NOTE:  ***** WARNING *****
+AVOID using the urb->dev field in your completion handler; it's cleared
+as part of URB unlinking.  Instead, use urb->context to hold all the
+data your driver needs.
+
+NOTE:  ***** WARNING *****
+Also, NEVER SLEEP IN A COMPLETION HANDLER.  These are normally called
+during hardware interrupt processing.  If you can, defer substantial
+work to a tasklet (bottom half) to keep system latencies low.  You'll
+probably need to use spinlocks to protect data structures you manipulate
+in completion handlers.
+
 
 1.8. How to do isochronous (ISO) transfers?
 
@@ -184,11 +209,13 @@
 in seamless ISO streaming. For continuous streaming you have to use URB
 linking. 
 
+
 1.9. How to start interrupt (INT) transfers?
 
-INT transfers are currently implemented with 8 different queues for intervals 
-for 1, 2, 4,... 128ms. Only one TD is allocated for each interrupt. After
-calling the completion handler, the TD is recycled.
+INT transfers are currently implemented with different queues for intervals 
+for 1, 2, 4,... 128ms. Only one URB is allocated for each interrupt. After
+calling the completion handler, that URB is recycled by the host controller
+driver (HCD).
 With the submission of one URB, the interrupt is scheduled until it is
 canceled by unlink_urb.