dect
/
linux-2.6
Archived
13
0
Fork 0
Code Releases Activity

USB: documentation update for usb_unlink_urb 

This patch (as936) updates the kerneldoc for usb_unlink_urb.  The
explanation of how endpoint queues are meant to work is now clearer
and in better agreement with reality.

Signed-off-by: Alan Stern <stern@rowland.harvard.edu>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
This commit is contained in:
Alan Stern 2007-07-13 15:47:16 -04:00 committed by Greg Kroah-Hartman
parent e7e7c360fb
commit beafef072a
1 changed files with 41 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
drivers/usb/core/urb.c
View File

@ -440,55 +440,57 @@ int usb_submit_urb(struct urb *urb, gfp_t mem_flags)
* @urb: pointer to urb describing a previously submitted request,
* may be NULL
*
* This routine cancels an in-progress request. URBs complete only
* once per submission, and may be canceled only once per submission.
* Successful cancellation means the requests's completion handler will
* be called with a status code indicating that the request has been
* canceled (rather than any other code) and will quickly be removed
* from host controller data structures.
* This routine cancels an in-progress request. URBs complete only once
* per submission, and may be canceled only once per submission.
* Successful cancellation means termination of @urb will be expedited
* and the completion handler will be called with a status code
* indicating that the request has been canceled (rather than any other
* code).
*
* This request is always asynchronous.
* Success is indicated by returning -EINPROGRESS,
* at which time the URB will normally have been unlinked but not yet
* given back to the device driver. When it is called, the completion
* function will see urb->status == -ECONNRESET. Failure is indicated
* by any other return value. Unlinking will fail when the URB is not
* currently "linked" (i.e., it was never submitted, or it was unlinked
* before, or the hardware is already finished with it), even if the
* completion handler has not yet run.
* This request is always asynchronous. Success is indicated by
* returning -EINPROGRESS, at which time the URB will probably not yet
* have been given back to the device driver. When it is eventually
* called, the completion function will see @urb->status == -ECONNRESET.
* Failure is indicated by usb_unlink_urb() returning any other value.
* Unlinking will fail when @urb is not currently "linked" (i.e., it was
* never submitted, or it was unlinked before, or the hardware is already
* finished with it), even if the completion handler has not yet run.
*
* Unlinking and Endpoint Queues:
*
* [The behaviors and guarantees described below do not apply to virtual
* root hubs but only to endpoint queues for physical USB devices.]
*
* Host Controller Drivers (HCDs) place all the URBs for a particular
* endpoint in a queue. Normally the queue advances as the controller
* hardware processes each request. But when an URB terminates with an
* error its queue stops, at least until that URB's completion routine
* returns. It is guaranteed that the queue will not restart until all
* its unlinked URBs have been fully retired, with their completion
* routines run, even if that's not until some time after the original
* completion handler returns. Normally the same behavior and guarantees
* apply when an URB terminates because it was unlinked; however if an
* URB is unlinked before the hardware has started to execute it, then
* its queue is not guaranteed to stop until all the preceding URBs have
* completed.
* error its queue generally stops (see below), at least until that URB's
* completion routine returns. It is guaranteed that a stopped queue
* will not restart until all its unlinked URBs have been fully retired,
* with their completion routines run, even if that's not until some time
* after the original completion handler returns. The same behavior and
* guarantee apply when an URB terminates because it was unlinked.
*
* This means that USB device drivers can safely build deep queues for
* large or complex transfers, and clean them up reliably after any sort
* of aborted transfer by unlinking all pending URBs at the first fault.
* Bulk and interrupt endpoint queues are guaranteed to stop whenever an
* URB terminates with any sort of error, including -ECONNRESET, -ENOENT,
* and -EREMOTEIO. Control endpoint queues behave the same way except
* that they are not guaranteed to stop for -EREMOTEIO errors. Queues
* for isochronous endpoints are treated differently, because they must
* advance at fixed rates. Such queues do not stop when an URB
* encounters an error or is unlinked. An unlinked isochronous URB may
* leave a gap in the stream of packets; it is undefined whether such
* gaps can be filled in.
*
* Note that an URB terminating early because a short packet was received
* will count as an error if and only if the URB_SHORT_NOT_OK flag is set.
* Also, that all unlinks performed in any URB completion handler must
* be asynchronous.
* Note that early termination of an URB because a short packet was
* received will generate a -EREMOTEIO error if and only if the
* URB_SHORT_NOT_OK flag is set. By setting this flag, USB device
* drivers can build deep queues for large or complex bulk transfers
* and clean them up reliably after any sort of aborted transfer by
* unlinking all pending URBs at the first fault.
*
* Queues for isochronous endpoints are treated differently, because they
* advance at fixed rates. Such queues do not stop when an URB is unlinked.
* An unlinked URB may leave a gap in the stream of packets. It is undefined
* whether such gaps can be filled in.
*
* When a control URB terminates with an error, it is likely that the
* status stage of the transfer will not take place, even if it is merely
* a soft error resulting from a short-packet with URB_SHORT_NOT_OK set.
* When a control URB terminates with an error other than -EREMOTEIO, it
* is quite likely that the status stage of the transfer will not take
* place.
*/
int usb_unlink_urb(struct urb *urb)
{