diff options
author | Linus Torvalds <torvalds@woody.linux-foundation.org> | 2007-07-20 08:25:49 -0700 |
---|---|---|
committer | Linus Torvalds <torvalds@woody.linux-foundation.org> | 2007-07-20 08:25:49 -0700 |
commit | 52a23685f37c06d0cd00eeb8f517a90de3f2c338 (patch) | |
tree | 1449bf12db013962c98b2b8cd9b4b5d1cf359b01 /drivers/usb/core/urb.c | |
parent | d046943cbaf332f75284ad99f4b3e60bae7ffff2 (diff) | |
parent | d20da3c39b9d5b04f0258ba74643533268f56e30 (diff) |
Merge master.kernel.org:/pub/scm/linux/kernel/git/gregkh/usb-2.6
* master.kernel.org:/pub/scm/linux/kernel/git/gregkh/usb-2.6: (44 commits)
USB: drivers/usb/storage/dpcm.c whitespace cleanup
USB: r8a66597-hcd: fixes some problem
USB: change name of spinlock in hcd.c
USB: move routines in hcd.c
USB: misc: uss720: clean up urb->status usage
USB: misc: usbtest: clean up urb->status usage
USB: misc: usblcd: clean up urb->status usage
USB: misc: phidgetmotorcontrol: clean up urb->status usage
USB: misc: phidgetkit: clean up urb->status usage
USB: misc: legousbtower: clean up urb->status usage
USB: misc: ldusb: clean up urb->status usage
USB: misc: iowarrior: clean up urb->status usage
USB: misc: ftdi-elan: clean up urb->status usage
USB: misc: auerswald: clean up urb->status usage
USB: misc: appledisplay: clean up urb->status usage
USB: misc: adtux: clean up urb->status usage
USB: core: message: clean up urb->status usage
USB: image: microtek: clean up urb->status usage
USB: image: mdc800: clean up urb->status usage
USB: storage: onetouch: clean up urb->status usage
...
Diffstat (limited to 'drivers/usb/core/urb.c')
-rw-r--r-- | drivers/usb/core/urb.c | 88 |
1 files changed, 45 insertions, 43 deletions
diff --git a/drivers/usb/core/urb.c b/drivers/usb/core/urb.c index 52ec44b828f..be630228461 100644 --- a/drivers/usb/core/urb.c +++ b/drivers/usb/core/urb.c @@ -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 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 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 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. - * - * 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. - * - * 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. - * - * 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. + * 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. + * + * 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 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. + * + * 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) { |