1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>usb_unlink_urb</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="The Linux-USB Host Side API"><link rel="up" href="usbcore.html" title="Chapter 5. USB Core APIs"><link rel="prev" href="API-usb-submit-urb.html" title="usb_submit_urb"><link rel="next" href="API-usb-kill-urb.html" title="usb_kill_urb"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center"><span class="phrase">usb_unlink_urb</span></th></tr><tr><td width="20%" align="left"><a accesskey="p" href="API-usb-submit-urb.html">Prev</a> </td><th width="60%" align="center">Chapter 5. USB Core APIs</th><td width="20%" align="right"> <a accesskey="n" href="API-usb-kill-urb.html">Next</a></td></tr></table><hr></div><div class="refentry"><a name="API-usb-unlink-urb"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>usb_unlink_urb — 2 abort/cancel a transfer request for an endpoint 3 </p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">usb_unlink_urb </b>(</code></td><td>struct urb * <var class="pdparam">urb</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idp1116000956"></a><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>urb</code></em></span></dt><dd><p> 4 pointer to urb describing a previously submitted request, 5 may be NULL 6 </p></dd></dl></div></div><div class="refsect1"><a name="idp1116002580"></a><h2>Description</h2><p> 7 This routine cancels an in-progress request. URBs complete only once 8 per submission, and may be canceled only once per submission. 9 Successful cancellation means termination of <em class="parameter"><code>urb</code></em> will be expedited 10 and the completion handler will be called with a status code 11 indicating that the request has been canceled (rather than any other 12 code). 13 </p><p> 14 15 Drivers should not call this routine or related routines, such as 16 <code class="function">usb_kill_urb</code> or <code class="function">usb_unlink_anchored_urbs</code>, after their disconnect 17 method has returned. The disconnect function should synchronize with 18 a driver's I/O routines to insure that all URB-related activity has 19 completed before it returns. 20 </p><p> 21 22 This request is asynchronous, however the HCD might call the -><code class="function">complete</code> 23 callback during unlink. Therefore when drivers call <code class="function">usb_unlink_urb</code>, they 24 must not hold any locks that may be taken by the completion function. 25 Success is indicated by returning -EINPROGRESS, at which time the URB will 26 probably not yet have been given back to the device driver. When it is 27 eventually called, the completion function will see <em class="parameter"><code>urb</code></em>->status == 28 -ECONNRESET. 29 Failure is indicated by <code class="function">usb_unlink_urb</code> returning any other value. 30 Unlinking will fail when <em class="parameter"><code>urb</code></em> is not currently <span class="quote">“<span class="quote">linked</span>”</span> (i.e., it was 31 never submitted, or it was unlinked before, or the hardware is already 32 finished with it), even if the completion handler has not yet run. 33 </p><p> 34 35 The URB must not be deallocated while this routine is running. In 36 particular, when a driver calls this routine, it must insure that the 37 completion handler cannot deallocate the URB. 38</p></div><div class="refsect1"><a name="idp1116007956"></a><h2>Return</h2><p> 39 -EINPROGRESS on success. See description for other values on 40 failure. 41</p></div><div class="refsect1"><a name="idp1116008620"></a><h2>Unlinking and Endpoint Queues</h2><p> 42 </p><p> 43 44 [The behaviors and guarantees described below do not apply to virtual 45 root hubs but only to endpoint queues for physical USB devices.] 46 </p><p> 47 48 Host Controller Drivers (HCDs) place all the URBs for a particular 49 endpoint in a queue. Normally the queue advances as the controller 50 hardware processes each request. But when an URB terminates with an 51 error its queue generally stops (see below), at least until that URB's 52 completion routine returns. It is guaranteed that a stopped queue 53 will not restart until all its unlinked URBs have been fully retired, 54 with their completion routines run, even if that's not until some time 55 after the original completion handler returns. The same behavior and 56 guarantee apply when an URB terminates because it was unlinked. 57 </p><p> 58 59 Bulk and interrupt endpoint queues are guaranteed to stop whenever an 60 URB terminates with any sort of error, including -ECONNRESET, -ENOENT, 61 and -EREMOTEIO. Control endpoint queues behave the same way except 62 that they are not guaranteed to stop for -EREMOTEIO errors. Queues 63 for isochronous endpoints are treated differently, because they must 64 advance at fixed rates. Such queues do not stop when an URB 65 encounters an error or is unlinked. An unlinked isochronous URB may 66 leave a gap in the stream of packets; it is undefined whether such 67 gaps can be filled in. 68 </p><p> 69 70 Note that early termination of an URB because a short packet was 71 received will generate a -EREMOTEIO error if and only if the 72 URB_SHORT_NOT_OK flag is set. By setting this flag, USB device 73 drivers can build deep queues for large or complex bulk transfers 74 and clean them up reliably after any sort of aborted transfer by 75 unlinking all pending URBs at the first fault. 76 </p><p> 77 78 When a control URB terminates with an error other than -EREMOTEIO, it 79 is quite likely that the status stage of the transfer will not take 80 place. 81</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="API-usb-submit-urb.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="usbcore.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="API-usb-kill-urb.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="phrase">usb_submit_urb</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> <span class="phrase">usb_kill_urb</span></td></tr></table></div></body></html> 82