James Courtier-Dutton wrote:
int usb_submit_urb (struct urb * urb, int mem_flags);
On return from this function call, which entries in the struct urb * urb can now be examined by the application?
struct urb { int start_frame;
I think the only one that changes validity at that time is start_frame. As documented with "struct urb".
};
Can the linux kernel documentation be expanded to include: -
Required values that need to be filled into struct urb for the call to work.
If you find anything that's not documented as being needed, let us know. Check both the "submit_urb" and the "struct urb" docs.
Return values that can be read safely from the struct urb after the submit_urb call.
start_frame.
Which return values can only be read during the urb_complete callback.
The only value documented as visible before complete() is the start_frame...
It would be nice if one could be sure the urb->start_frame is valid after this call.
The docs say you can be sure of that for any reserved-bandwidth transfer.
The kernel docs have a nice section on what values to give the "int mem_flags" argument, but next to nothing for the "strub urb *urb" argument.
Except as part of the "struct urb" documentation? :)
- Dave
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.
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 ?
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.
Also, another point: -
Terminology is a bit confusing at times.
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.
Suggested rewrite: -
URBs are queued because they can be submitted to endpoints before 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 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.
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."
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.
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?
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
