From: Alan Stern Date: Fri, 13 Jul 2007 19:47:16 +0000 (-0400) Subject: USB: documentation update for usb_unlink_urb X-Git-Tag: v2.6.23-rc1~231^2~31 X-Git-Url: https://err.no/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=beafef072af10bc8497c9ee51ce2804aa7da26be;p=linux-2.6 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 Signed-off-by: Greg Kroah-Hartman --- diff --git a/drivers/usb/core/urb.c b/drivers/usb/core/urb.c index 52ec44b828..be63022846 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) {