Hi,
Given the discussions of last week, this removes urb->next from
the USB core API. This change simplifies the driver API by getting
rid of a superfluous feature (and related new-developer confusion),
gets rid of a hidden failure mode (drivers can now see resubmit
failures), lets us get rid of a HCD feature that isn't consistently
implemented, and so on.
This will break some code. There are ISO drivers that don't use
urb->next (like audio), but most video drivers do. My patch #2
fixes one such driver. My patch #3 fixes host controller drivers,
most of which were already converted.
- Dave
--- ./include/linux/usb.h-dist Sat May 18 18:42:23 2002
+++ ./include/linux/usb.h Tue May 21 09:07:48 2002
@@ -767,7 +767,6 @@
/**
* struct urb - USB Request Block
* @urb_list: For use by current owner of the URB.
- * @next: Used to link ISO requests into rings.
* @pipe: Holds endpoint number, direction, type, and max packet size.
* Create these values with the eight macros available;
* usb_{snd,rcv}TYPEpipe(dev,endpoint), where the type is "ctrl"
@@ -827,7 +826,7 @@
*
* Initialization:
*
- * All URBs submitted must initialize dev, pipe, next (may be null),
+ * All URBs submitted must initialize dev, pipe,
* transfer_flags (may be zero), complete, timeout (may be zero).
* The USB_ASYNC_UNLINK transfer flag affects later invocations of
* the usb_unlink_urb() routine.
@@ -873,7 +872,9 @@
* the quality of service is only "best effort". Callers provide specially
* allocated URBs, with number_of_packets worth of iso_frame_desc structures
* at the end. Each such packet is an individual ISO transfer. Isochronous
- * URBs are normally submitted with urb->next fields set up as a ring, so
+ * URBs are normally queued (no flag like USB_BULK_QUEUE is needed) so that
+ * transfers are at least double buffered, and then explicitly resubmitted
+ * in completion handlers, so
* that data (such as audio or video) streams at as constant a rate as the
* host controller scheduler can support.
*
@@ -891,14 +892,15 @@
* When completion callback is invoked for non-isochronous URBs, the
* actual_length field tells how many bytes were transferred.
*
- * For interrupt and isochronous URBs, the URB provided to the callback
+ * For interrupt URBs, the URB provided to the callback
* function is still "owned" by the USB core subsystem unless the status
* indicates that the URB has been unlinked. Completion handlers should
* not modify such URBs until they have been unlinked.
*
* ISO transfer status is reported in the status and actual_length fields
* of the iso_frame_desc array, and the number of errors is reported in
- * error_count.
+ * error_count. Completion callbacks for ISO transfers will normally
+ * (re)submit URBs to ensure a constant transfer rate.
*/
struct urb
{
@@ -906,7 +908,6 @@
atomic_t count; /* reference count of the URB */
void *hcpriv; /* private data for host controller */
struct list_head urb_list; /* list pointer to all active urbs */
- struct urb *next; /* (in) pointer to next URB */
struct usb_device *dev; /* (in) pointer to associated device */
unsigned int pipe; /* (in) pipe information */
int status; /* (return) non-ISO status */
--- ./drivers/usb-dist/core/hcd.c Sat May 18 18:42:07 2002
+++ ./drivers/usb/core/hcd.c Tue May 21 09:08:21 2002
@@ -1407,11 +1407,6 @@
if (urb->transfer_buffer_length < 0)
return -EINVAL;
- if (urb->next) {
- warn ("use explicit queuing not urb->next");
- return -EINVAL;
- }
-
#ifdef DEBUG
/* stuff that drivers shouldn't do, but which shouldn't
* cause problems in HCDs if they get it wrong.
@@ -1785,10 +1780,6 @@
* HCDs must not use this for periodic URBs that are still scheduled
* and will be reissued. They should just call their completion handlers
* until the urb is returned to the device driver by unlinking.
- *
- * NOTE that no urb->next processing is done, even for isochronous URBs.
- * ISO streaming functionality can be achieved by having completion handlers
- * re-queue URBs. Such explicit queuing doesn't discard error reports.
*/
void usb_hcd_giveback_urb (struct usb_hcd *hcd, struct urb *urb)
{
--- ./drivers/usb-dist/core/devio.c Tue Apr 23 08:46:40 2002
+++ ./drivers/usb/core/devio.c Tue May 21 09:10:24 2002
@@ -892,7 +892,6 @@
free_async(as);
return -ENOMEM;
}
- as->urb->next = NULL;
as->urb->dev = ps->dev;
as->urb->pipe = (uurb.type << 30) | __create_pipe(ps->dev, uurb.endpoint &
0xf) | (uurb.endpoint & USB_DIR_IN);
as->urb->transfer_flags = uurb.flags;
--- ./drivers/usb-dist/core/usb-debug.c Sun Apr 14 12:18:51 2002
+++ ./drivers/usb/core/usb-debug.c Tue May 21 09:12:36 2002
@@ -184,7 +184,6 @@
void usb_dump_urb (struct urb *urb)
{
printk ("urb :%p\n", urb);
- printk ("next :%p\n", urb->next);
printk ("dev :%p\n", urb->dev);
printk ("pipe :%08X\n", urb->pipe);
printk ("status :%d\n", urb->status);
