USB_HCD_LINK_URB_TO_(9) Host Controller APIs USB_HCD_LINK_URB_TO_(9)NAME
usb_hcd_link_urb_to_ep - add an URB to its endpoint queue
SYNOPSIS
int usb_hcd_link_urb_to_ep(struct usb_hcd * hcd, struct urb * urb);
ARGUMENTS
hcd
host controller to which urb was submitted
urb
URB being submitted
DESCRIPTION
Host controller drivers should call this routine in their enqueue method. The HCD's private spinlock must be held and interrupts must be
disabled. The actions carried out here are required for URB submission, as well as for endpoint shutdown and for usb_kill_urb.
RETURN
0 for no error, otherwise a negative error code (in which case the enqueue method must fail). If no error occurs but enqueue fails anyway,
it must call usb_hcd_unlink_urb_from_ep before releasing the private spinlock and returning.
COPYRIGHT Kernel Hackers Manual 3.10 June 2014 USB_HCD_LINK_URB_TO_(9)
Check Out this Related Man Page
USB_UNLINK_URB(9) USB Core APIs USB_UNLINK_URB(9)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 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).
Drivers should not call this routine or related routines, such as usb_kill_urb or usb_unlink_anchored_urbs, after their disconnect method
has returned. The disconnect function should synchronize with a driver's I/O routines to insure that all URB-related activity has completed
before it returns.
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 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.
COPYRIGHT Kernel Hackers Manual 2.6. July 2010 USB_UNLINK_URB(9)