Provided by: linux-doc-2.6.15_2.6.15-23.39_all bug

NAME

       usb_unlink_urb - abort/cancel a transfer request for an endpoint

SYNOPSIS

       int usb_unlink_urb  (struct urb * urb);

ARGUMENTS

       urb    pointer to urb describing a previously submitted request, may be
              NULL

DESCRIPTION

       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.

UNLINKING AND ENDPOINT QUEUES

       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.