1USB_UNLINK_URB(9) USB Core APIs USB_UNLINK_URB(9)
2
6 usb_unlink_urb - abort/cancel a transfer request for an endpoint
7
9 int usb_unlink_urb(struct urb * urb);
10
12 urb
13 pointer to urb describing a previously submitted request, may be
14 NULL
15
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 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 This request is always asynchronous. Success is indicated by returning
30 -EINPROGRESS, at which time the URB will probably not yet have been
31 given back to the device driver. When it is eventually called, the
32 completion function will see urb->status == -ECONNRESET. Failure is
33 indicated by usb_unlink_urb returning any other value. Unlinking will
34 fail when urb is not currently “linked” (i.e., it was never submitted,
35 or it was unlinked before, or the hardware is already finished with
36 it), even if the completion handler has not yet run.
37
39 [The behaviors and guarantees described below do not apply to virtual
40 root hubs but only to endpoint queues for physical USB devices.]
41 Host Controller Drivers (HCDs) place all the URBs for a particular
43 endpoint in a queue. Normally the queue advances as the controller
44 hardware processes each request. But when an URB terminates with an
45 error its queue generally stops (see below), at least until that URB's
46 completion routine returns. It is guaranteed that a stopped queue will
47 not restart until all its unlinked URBs have been fully retired, with
48 their completion routines run, even if that's not until some time after
49 the original completion handler returns. The same behavior and
50 guarantee apply when an URB terminates because it was unlinked.
51 Bulk and interrupt endpoint queues are guaranteed to stop whenever an
53 URB terminates with any sort of error, including -ECONNRESET, -ENOENT,
54 and -EREMOTEIO. Control endpoint queues behave the same way except that
55 they are not guaranteed to stop for -EREMOTEIO errors. Queues for
56 isochronous endpoints are treated differently, because they must
57 advance at fixed rates. Such queues do not stop when an URB encounters
58 an error or is unlinked. An unlinked isochronous URB may leave a gap in
59 the stream of packets; it is undefined whether such gaps can be filled
60 in.
61 Note that early termination of an URB because a short packet was
63 received will generate a -EREMOTEIO error if and only if the
64 URB_SHORT_NOT_OK flag is set. By setting this flag, USB device drivers
65 can build deep queues for large or complex bulk transfers and clean
66 them up reliably after any sort of aborted transfer by unlinking all
67 pending URBs at the first fault.
68 When a control URB terminates with an error other than -EREMOTEIO, it
70 is quite likely that the status stage of the transfer will not take
71 place.
72
74Kernel Hackers Manual 2.6. November 2011 USB_UNLINK_URB(9)