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

• Lines: 176
• Date: Tue Dec 5 23:15:11 2000
• Orig file: v2.4.0-test11/linux/Documentation/usb/URB.txt
• Orig date: Sun Oct 8 10:50:04 2000

diff -u --recursive --new-file v2.4.0-test11/linux/Documentation/usb/URB.txt linux/Documentation/usb/URB.txt
@@ -1,3 +1,5 @@
+Revised: 2000-Dec-05.
+
 1. Specification of the API
 
 1.1. Basic concept or 'What is an URB?'
@@ -8,16 +10,16 @@
 - An URB consists of all relevant information to execute any USB transaction 
 and deliver the data and status back. 
 
-- Execution of an URB is an inherently asynchronous operation, i.e. the 
-submit_urb(urb) call returns immediately after it has successfully queued 
+- Execution of an URB is inherently an asynchronous operation, i.e. the 
+usb_submit_urb(urb) call returns immediately after it has successfully queued 
 the requested action. 
 
 - Ongoing transfers for one URB (e.g. ISO) can simply be canceled with
-unlink_urb(urb) at any time. 
+usb_unlink_urb(urb) at any time. 
 
 - Each URB has a completion handler, which is called after the action
 has been successfully completed or canceled (INT transfers behave a bit
-different, see below). The URB also contains a context-pointer for free 
+differently, see below). The URB also contains a context-pointer for free 
 usage and information passing to the completion handler.
 
 - URBs can be linked. After completing one URB, the next one can be
@@ -31,6 +33,8 @@
 
 typedef struct urb
 {
+	spinlock_t lock;		// lock for the URB
+
 // ignore, for host controller/URB machine internal use
 	void *hcpriv;                   // private data for host controller
 	struct list_head urb_list;      // list pointer to all active urbs 
@@ -39,12 +43,12 @@
 	struct urb* next;               // pointer to next URB  
 	struct usb_device *dev;         // pointer to associated USB device
 
-// pipe is assembled by the various well known pipe-macros in usb.h
+// pipe is assembled by the various well-known pipe macros in usb.h
 	unsigned int pipe;              // pipe information
 
 // status after each completion
 	int status;                     // returned status
-	unsigned int transfer_flags;    // ASAP, SP_OK, etc.
+	unsigned int transfer_flags;    // ASAP, DISABLE_SPD, etc.
 
 // for data stage (CTRL), BULK, INT and ISO
 	void *transfer_buffer;          // associated data buffer
@@ -55,7 +59,7 @@
 
 // setup stage for CTRL (always 8 bytes!)
 	unsigned char* setup_packet;    // setup packet (control only)
-	
+
 // with ASAP, start_frame is set to the determined frame
 	int start_frame;                // start frame (iso/irq)
 	int number_of_packets;          // # of packets (iso/int)
@@ -66,7 +70,7 @@
 	usb_complete_t complete;        // pointer to completion routine
 	//
 // specification of the requested data offsets and length for ISO
-	iso_packet_descriptor_t  iso_frame_desc[0];
+	iso_packet_descriptor_t iso_frame_desc[0];
 } urb_t, *purb_t;
 
 
@@ -74,7 +78,7 @@
 
 URBs are allocated with the following call
 
-	purb_t alloc_urb(int isoframes)
+	purb_t usb_alloc_urb(int isoframes)
 
 Return value is a pointer to the allocated URB, 0 if allocation failed.
 The parameter isoframes specifies the number of isochronous transfer frames
@@ -82,7 +86,7 @@
 
 To free an URB, use
 
-	void free_urb(purb_t purb)
+	void usb_free_urb(purb_t purb)
 
 This call also may free internal (host controller specific) memory in the
 future.
@@ -91,12 +95,13 @@
 1.4. What has to be filled in?
 
 Depending on the type of transaction, there are some macros 
-(FILL_CONTROL_URB, FILL_BULK_URB, and FILL_INT_URB, defined in uhci.h)
+(FILL_CONTROL_URB, FILL_CONTROL_URB_TO, FILL_BULK_URB,
+FILL_BULK_URB_TO, and FILL_INT_URB, defined in usb.h)
 that simplify the URB creation. In general, all macros need the usb
-device pointer, the pipe (usual format), the transfer buffer, the 
-desired transfer length, the completion  handler, and its context. 
-Take a look at the uhci_control_msg-function that convert the old API 
-into an URB.
+device pointer, the pipe (usual format from usb.h), the transfer buffer,
+the desired transfer length, the completion  handler, and its context. 
+Take a look at the usb_control_msg function that converts the old API 
+into the URB API.
 
 Flags:
 For ISO there are two startup behaviors: Specified start_frame or ASAP.
@@ -114,7 +119,7 @@
 
 Just call
 
-	int submit_urb(purb_t purb)
+	int usb_submit_urb(purb_t purb)
 
 It immediately returns, either with status 0 (request queued) or some
 error code, usually caused by the following:
@@ -128,7 +133,7 @@
 - Invalid INT interval (-EINVAL)
 - More than one packet for INT (-EINVAL)
 
-After submission, urb->status is USB_ST_URB_PENDING.
+After submission, urb->status is USB_ST_URB_PENDING (-EINPROGRESS).
 
 For isochronous endpoints, subsequent submitting of URBs to the same endpoint
 with the ASAP flag result in a seamless ISO streaming. Exception: The 
@@ -142,18 +147,18 @@
 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)
+	int usb_unlink_urb(purb_t purb)
 
 It removes the urb from the internal list and frees all allocated
 HW descriptors. The status is changed to USB_ST_URB_KILLED. After 
-unlink_urb() returns, you can safely free the URB with free_urb(urb)
+usb_unlink_urb() returns, you can safely free the URB with usb_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.
+normally be unlinked when usb_unlink_urb() returns.  Instead, wait
+for the completion handler to be called.
 
 
 1.7. What about the completion handler?
@@ -187,13 +192,13 @@
 1.8. How to do isochronous (ISO) transfers?
 
 For ISO transfers you have to append the iso_packet_descriptor_t structure 
-to the URB for each frame you want to schedule. When using alloc_urb(n)
-(recommended), the isoframe-parameter n can be used to allocate the
-structures for n frames.
+to the URB for each frame you want to schedule. When using usb_alloc_urb(n)
+(recommended), the iso_packets parameter can be used to allocate the
+structures for iso_packets frames.
 
 For each entry you have to specify the data offset for this frame (base is
 transfer_buffer), and the length you want to write/expect to read.
-After completion, actual_length contains the actual transfered length and 
+After completion, actual_length contains the actual transferred length and 
 status contains the resulting USB-status for the ISO transfer for this frame.
 It is allowed to specify a varying length from frame to frame (e.g. for
 audio synchronisation/adaptive transfer rates). You can also use the length 
@@ -217,7 +222,7 @@
 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.
-
-The submit_urb()-call modifies urb->interval to the rounded value.
+canceled by usb_unlink_urb.
 
+The usb_submit_urb() call modifies urb->interval to the implemented interval
+value that is less than or equal to the requested interval value.