Commit beafef07 authored by Alan Stern's avatar Alan Stern Committed by Greg Kroah-Hartman

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