1USB_UNLINK_URB(9)                USB Core APIs               USB_UNLINK_URB(9)
2
3
4

NAME

6       usb_unlink_urb - abort/cancel a transfer request for an endpoint
7

SYNOPSIS

9       int usb_unlink_urb(struct urb * urb);
10

ARGUMENTS

12       urb
13           pointer to urb describing a previously submitted request, may be
14           NULL
15

DESCRIPTION

17       This routine cancels an in-progress request. URBs complete only once
18       per submission, and may be canceled only once per submission.
19       Successful cancellation means termination of urb will be expedited and
20       the completion handler will be called with a status code indicating
21       that the request has been canceled (rather than any other code).
22
23       Drivers should not call this routine or related routines, such as
24       usb_kill_urb or usb_unlink_anchored_urbs, after their disconnect method
25       has returned. The disconnect function should synchronize with a
26       driver's I/O routines to insure that all URB-related activity has
27       completed before it returns.
28
29       This request is asynchronous, however the HCD might call the ->complete
30       callback during unlink. Therefore when drivers call usb_unlink_urb,
31       they must not hold any locks that may be taken by the completion
32       function. Success is indicated by returning -EINPROGRESS, at which time
33       the URB will probably not yet have been given back to the device
34       driver. When it is eventually called, the completion function will see
35       urb->status == -ECONNRESET. Failure is indicated by usb_unlink_urb
36       returning any other value. Unlinking will fail when urb is not
37       currently “linked” (i.e., it was never submitted, or it was unlinked
38       before, or the hardware is already finished with it), even if the
39       completion handler has not yet run.
40
41       The URB must not be deallocated while this routine is running. In
42       particular, when a driver calls this routine, it must insure that the
43       completion handler cannot deallocate the URB.
44

RETURN

46       -EINPROGRESS on success. See description for other values on failure.
47

UNLINKING AND ENDPOINT QUEUES

49       [The behaviors and guarantees described below do not apply to virtual
50       root hubs but only to endpoint queues for physical USB devices.]
51
52       Host Controller Drivers (HCDs) place all the URBs for a particular
53       endpoint in a queue. Normally the queue advances as the controller
54       hardware processes each request. But when an URB terminates with an
55       error its queue generally stops (see below), at least until that URB's
56       completion routine returns. It is guaranteed that a stopped queue will
57       not restart until all its unlinked URBs have been fully retired, with
58       their completion routines run, even if that's not until some time after
59       the original completion handler returns. The same behavior and
60       guarantee apply when an URB terminates because it was unlinked.
61
62       Bulk and interrupt endpoint queues are guaranteed to stop whenever an
63       URB terminates with any sort of error, including -ECONNRESET, -ENOENT,
64       and -EREMOTEIO. Control endpoint queues behave the same way except that
65       they are not guaranteed to stop for -EREMOTEIO errors. Queues for
66       isochronous endpoints are treated differently, because they must
67       advance at fixed rates. Such queues do not stop when an URB encounters
68       an error or is unlinked. An unlinked isochronous URB may leave a gap in
69       the stream of packets; it is undefined whether such gaps can be filled
70       in.
71
72       Note that early termination of an URB because a short packet was
73       received will generate a -EREMOTEIO error if and only if the
74       URB_SHORT_NOT_OK flag is set. By setting this flag, USB device drivers
75       can build deep queues for large or complex bulk transfers and clean
76       them up reliably after any sort of aborted transfer by unlinking all
77       pending URBs at the first fault.
78
79       When a control URB terminates with an error other than -EREMOTEIO, it
80       is quite likely that the status stage of the transfer will not take
81       place.
82
84Kernel Hackers Manual 3.10         June 2019                 USB_UNLINK_URB(9)
Impressum