All CAPS here denote headings, and not shouting.
Ok, I have checked the docs now, and would like to make a few suggestions. The docs might all be clear to you, but often they are not so clear to the first time reader.
There's been a shortage of careful "first time reader" reviews! And for that matter, "editor" treatment is clearly needed. On the plus side, I think the raw data is mostly accurate.
I was sort of hoping for a man page type entry. E.g. man open We have main headings of: - NAME SYNOPSIS DESCRIPTION RETURN VALUE ERRORS etc.
In the kernel docs we only have: - NAME SYNOPSIS DESCRIPTION
Can we add RETURN VALUE and ERRORS headings to the kernel docs ?
Easy to add "Return Value:" and "Errors:" sections to the kerneldoc, at least for USB procedures if not as a kernel-wide standard.
The kernel docs have this under submit_urb description
"Successful submissions return 0; otherwise this routine returns a negative error number. If the submission is successful, the complete callback from the urb will be called exactly once, when the USB core and host controller driver are finished with the urb. When the completion function is called, control of the URB is returned to the device driver which issued the request. The completion handler may then immediately free or reuse that URB."
I think this would be better placed under a "RETURN VALUE" heading.
Could be, but the specific semantics extend beyond a return value; they're procedure definition: the point of the routine is to cause that complete() callback after I/O (or cancelation). That callback isn't a return value of this function; it's a distinct interface to (from) usbcore in its own right.
Also, another point: - Terminology is a bit confusing at times.
History in action!!
Under "name" we have: - usb_submit_urb - issue an asynchronous transfer request for an endpoint
Then under "Request Queuing" we have
"URBs may be submitted to endpoints before previous ones complete, to minimize the impact of interrupt latencies and system overhead on data throughput. This is required for continuous isochronous data streams, and may also be required for some kinds of interrupt transfers. Such queueing also maximizes bandwidth utilization by letting USB controllers start work on later requests before driver software has finished the completion processing for earlier requests."
The phrase "Such queueing" is wrong for two reasons. 1) spelling, 2) Gramma. One cannot use the term "such queuing" without first using the term earlier in the paragraph.
If one realizes that "submit" == "queue" (verb), then things look a bit different (speling aside). "Such queuing" as described in the first sentence. That'd be clarified by adding a sentence after the first one, highlighting the key point: "With that queueing policy, the endpoint's queue would never be empty."
Suggested rewrite: -
URBs are queued because they can be submitted to endpoints before
The essential point is that "queue length never zero" provides the goodness of minimized latencies, maximized throuhgput, etc.
previous ones complete. Queuing minimizes the impact of interrupt latencies and system overhead on data throughput. This is required for continuous isochronous data streams, and may also be required for some kinds of interrupt transfers. Such queuing also maximizes bandwidth utilization by letting USB controllers start work on later requests before driver software has finished the completion processing for earlier requests.
So, we have now established, from the documentation, that usb_submit_urb adds an item to the queue. We do not know if the urb has been scheduled
The word "scheduled" has not been introduced. I don't think it's needed here.
The essential guarantee was already described: when a driver gets the callback. How that may map to anything else is HCD-specific.
yet. We also do not know if the "submission" stage is complete after a usb_submit_urb() or that instead the "submission" is only complete once we have a completion event.
Hmm?? We _do_ know that "submission" is done ... because submit() returned!
The async compltion callback happens well after the role of submit() in the urb lifecycle has finished.
Under "struct urb" -> "Initialization" we have the sentence:
"After the URB has been submitted, the interval and start_frame fields reflect how the transfer was actually scheduled."
... which may not currently be true in all cases, but those would be bugs ...
Is the urb scheduled between usb_submit_urb() and the completion event or during the usb_submit_urb() call?
Suggest rewrite:
"During usb_submit_urb() the transfer is scheduled. The interval and start_frame fields reflect how the transfer was actually scheduled."
and add that to the "RETURN VALUE" description.
That sounds very good, for periodic transfers.
and also
"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."
It is not totally clear that the phrase "during submission" means "during urb_submit_urb()" because
"usb_submit_urb - issue an asynchronous transfer request for an endpoint".
"during submission" could mean anytime between the usb_submit_urb() and the resulting completion event.
Can changes be made to the documentation to clarify this?
See /usr/src/linux/Documentation/SubmittingPatches ... in this case, post to linux-usb-devel. :)
- Dave
Cheers James
------------------------------------------------------- SF.Net is sponsored by: Speed Start Your Linux Apps Now. Build and deploy apps & Web services for Linux with a free DVD software kit from IBM. Click Now! http://ads.osdn.com/?ad_id=1356&alloc_id=3438&op=click _______________________________________________ [EMAIL PROTECTED] To unsubscribe, use the last form field at: https://lists.sourceforge.net/lists/listinfo/linux-usb-devel
