Updated doumentation revisions...
Alan Stern
Index: usb-2.6/include/linux/usb.h
===================================================================
--- usb-2.6.orig/include/linux/usb.h
+++ usb-2.6/include/linux/usb.h
@@ -765,14 +765,20 @@ extern int usb_disabled(void);
* urb->transfer_flags:
*/
#define URB_SHORT_NOT_OK 0x0001 /* report short reads as errors */
-#define URB_ISO_ASAP 0x0002 /* iso-only, urb->start_frame
- * ignored */
#define URB_NO_TRANSFER_DMA_MAP 0x0004 /* urb->transfer_dma valid on
submit */
#define URB_NO_SETUP_DMA_MAP 0x0008 /* urb->setup_dma valid on submit */
#define URB_NO_FSBR 0x0020 /* UHCI-specific */
#define URB_ZERO_PACKET 0x0040 /* Finish bulk OUT with short
packet */
#define URB_NO_INTERRUPT 0x0080 /* HINT: no non-error interrupt
* needed */
+#define URB_ISO_ASAP 0x0100 /* Schedule ISO packets to start in the
+ * next upcoming time slot, ignoring
+ * urb->start_frame */
+#define URB_ISO_NO_SKIP 0x0200 /* Schedule ISO packets to
start in the
+ * time slot after the end of the
+ * previous URB for this endpoint (even
+ * if it has already expired), ignoring
+ * urb->start_frame. */
struct usb_iso_packet_descriptor {
unsigned int offset;
@@ -904,25 +910,77 @@ typedef void (*usb_complete_t)(struct ur
* the transfer interval in the endpoint descriptor is logarithmic.
* Device drivers must convert that value to linear units themselves.)
*
- * Isochronous URBs normally use the URB_ISO_ASAP transfer flag, telling
- * the host controller to schedule the transfer as soon as bandwidth
- * utilization allows, and then set start_frame to reflect the actual frame
- * selected during submission. Otherwise drivers must specify the start_frame
- * and handle the case where the transfer can't begin then. However, drivers
- * won't know how bandwidth is currently allocated, and while they can
- * find the current frame using usb_get_current_frame_number () they can't
- * know the range for that frame number. (Ranges for frame counter values
- * are HC-specific, and can go from 256 to 65536 frames from "now".)
+ * Periodic transfers
*
- * Isochronous URBs have a different data transfer model, in part because
+ * Isochronous URBs have a special data transfer model, in part because
* 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 queued, submitted by drivers to arrange 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.
+ * URBs are normally queued, submitted by drivers so that transfers are
+ * at least double-buffered and then explicitly resubmitted in completion
+ * handlers. This allows data (such as audio or video) to stream at as
+ * constant a rate as the host controller hardware and software scheduler
+ * can support.
+ *
+ * Interrupt and isochronous URBs require bandwidth to be allocated and
+ * reserved, guaranteeing timely access to the bus. The allocation is made
+ * automatically when the first URB for an endpoint is submitted, and the
+ * bandwidth remains reserved until no more URBs are pending and all
+ * completion handlers for the endpoint's URBs have returned. In addition
+ * to the bandwidth itself, a schedule of time slots is allocated for the
+ * endpoint. With interrupt endpoints the choice of time slots is entirely
+ * up to the host controller driver, but with isochronous endpoints the
+ * driver has a little more control.
+ *
+ * With each submitted URB, the driver can specify a scheduling policy by
+ * setting either of USB_ISO_ASAP or URB_ISO_NO_SKIP in transfer_flags
+ * (not both!) or else setting start_frame.
+ *
+ * (o) If USB_ISO_ASAP is set and this is the first URB for an
+ * endpoint stream then the host controller driver will select
+ * a frame or micro-frame in the near future as the initial time
+ * slot, available bandwidth permitting. For URBs submitted after
+ * the stream has been established, URB_ISO_ASAP tells the host
+ * controller driver to schedule the first packet of the URB in an
+ * upcoming time slot, skipping over time slots that have already
+ * expired. (Hardware restrictions may force the URB to be scheduled
+ * somewhat farther in the future than the very next upcoming slot.)
+ *
+ * (o) For the first URB in an endpoint stream, URB_ISO_NO_SKIP is
+ * treated the same as URB_ISO_ASAP. For later URBs,
+ * URB_ISO_NO_SKIP tells the host controller driver to schedule
+ * the first packet of the URB in the time slot following the end
+ * of the previous URB for this endpoint, even if that slot has
+ * already expired.
+ *
+ * (o) If neither flag is set for the first URB in an endpoint stream,
+ * the value of start_frame will be used for the initial time slot.
+ * For later URBs, lack of either flag tells the host controller
+ * driver to schedule the URB's first packet in the (micro-)frame
+ * specified by start_frame, which then must correspond to one of
+ * the endpoint's allocated time slots. If the previous URB had
+ * number_of_packets set to N and its start_frame was S, then the
+ * current URB's start_frame can be set to S + (N+x)*I, where I is
+ * the transfer interval in (micro-)frames and x is a small unsigned
+ * integer. If the host controller driver supports the start_frame
+ * mechanism at all, such a start_frame value would be accepted
+ * provided that x*I is less than one second (1000 for full speed,
+ * 8000 for high speed).
+ *
+ * Some host controller drivers may not support all three options, although
+ * they all support USB_ISO_ASAP; an unsupported option is rejected with
+ * a -ENXIO error code. With any of the options, if an URB is submitted so
+ * late that all of its packets' time slots have already expired then the
+ * submission will fail with a -EL2NSYNC error code. With the first two
+ * options, after a successful submission start_frame will be set to the
+ * actual (micro-)frame selected selected for the URB's first packet.
+ *
+ * Normally drivers will use URB_ISO_ASAP or USB_ISO_NO_SKIP (which one
+ * depends on whether the driver wants to maintain a strict one-to-one
+ * relation between iso_frame_descriptors and sequential time slots).
+ * Specifying a start_frame value for the first URB in a stream is less
+ * reliable than allowing the host controller driver to select the initial
+ * frame, because the driver isn't aware of the current bandwidth allocation.
*
* Completion Callbacks:
*
Index: usb-2.6/Documentation/usb/error-codes.txt
===================================================================
--- usb-2.6.orig/Documentation/usb/error-codes.txt
+++ usb-2.6/Documentation/usb/error-codes.txt
@@ -1,4 +1,4 @@
-Revised: 2004-Oct-21
+Revised: 2006-Oct-25
This is the documentation of (hopefully) all possible error codes (and
their interpretation) that can be returned from usbcore.
@@ -26,8 +26,9 @@ USB-specific:
-ENOENT specified interface or endpoint does not exist or
is not enabled
--ENXIO host controller driver does not support queuing of this type
- of urb. (treat as a host controller bug.)
+-ENXIO Host controller driver does not support queuing of this type
+ of URB or does not support the requested URB_ISO_...
+ scheduling flag.
-EINVAL a) Invalid transfer type specified (or not supported)
b) Invalid or unsupported periodic transfer interval
@@ -35,11 +36,15 @@ USB-specific:
d) ISO: number_of_packets is < 0
e) various other cases
--EAGAIN a) specified ISO start frame too early
- b) (using ISO-ASAP) too much scheduled for the future
- wait some time and try again.
+-EL2NSYNC Specified ISO start frame is too early; the time slots for
+ all the frame descriptors in the URB have already expired.
+ urb->start_frame is set to the next upcoming time slot.
--EFBIG Host controller driver can't schedule that many ISO frames.
+-EDOM Specified ISO start frame is not one of those allocated to
+ the endpoint's bandwidth reservation.
+
+-EFBIG Host controller driver can't schedule that many ISO frames
+ or that far into the future.
-EPIPE Specified endpoint is stalled. For non-control endpoints,
reset this status with usb_clear_halt().
@@ -129,10 +134,11 @@ one or more packets could finish before
other errors, since the hub driver doesn't detect
device removal events immediately.
--EXDEV ISO transfer only partially completed
- look at individual frame status for details
-
--EINVAL ISO madness, if this happens: Log off and go
home
+-EL2NSYNC ISO transfer only partially completed. In an
+ individual frame descriptor status this means the
+ host did not try to transfer the packet, probably
+ because the URB was submitted after the packet's
+ time slot had expired.
-ECONNRESET URB was asynchronously unlinked by usb_unlink_urb
-------------------------------------------------------------------------
Using Tomcat but need to do more? Need to support web services, security?
Get stuff done quickly with pre-integrated technology to make your job easier
Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
_______________________________________________
linux-usb-devel@lists.sourceforge.net
To unsubscribe, use the last form field at:
https://lists.sourceforge.net/lists/listinfo/linux-usb-devel
