Name

usb_unlink_urb — abort/cancel a transfer request for an endpoint

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.