1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>usb_submit_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-unanchor-urb.html" title="usb_unanchor_urb"><link rel="next" href="API-usb-unlink-urb.html" title="usb_unlink_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_submit_urb</span></th></tr><tr><td width="20%" align="left"><a accesskey="p" href="API-usb-unanchor-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-unlink-urb.html">Next</a></td></tr></table><hr></div><div class="refentry"><a name="API-usb-submit-urb"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>usb_submit_urb — 2 issue an asynchronous 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_submit_urb </b>(</code></td><td>struct urb * <var class="pdparam">urb</var>, </td></tr><tr><td> </td><td>gfp_t <var class="pdparam">mem_flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idp1115978876"></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 the urb describing the request 5 </p></dd><dt><span class="term"><em class="parameter"><code>mem_flags</code></em></span></dt><dd><p> 6 the type of memory to allocate, see <code class="function">kmalloc</code> for a list 7 of valid options for this. 8 </p></dd></dl></div></div><div class="refsect1"><a name="idp1115981836"></a><h2>Description</h2><p> 9 This submits a transfer request, and transfers control of the URB 10 describing that request to the USB subsystem. Request completion will 11 be indicated later, asynchronously, by calling the completion handler. 12 The three types of completion are success, error, and unlink 13 (a software-induced fault, also called <span class="quote">“<span class="quote">request cancellation</span>”</span>). 14 </p><p> 15 16 URBs may be submitted in interrupt context. 17 </p><p> 18 19 The caller must have correctly initialized the URB before submitting 20 it. Functions such as <code class="function">usb_fill_bulk_urb</code> and <code class="function">usb_fill_control_urb</code> are 21 available to ensure that most fields are correctly initialized, for 22 the particular kind of transfer, although they will not initialize 23 any transfer flags. 24 </p><p> 25 26 If the submission is successful, the <code class="function">complete</code> callback from the URB 27 will be called exactly once, when the USB core and Host Controller Driver 28 (HCD) are finished with the URB. When the completion function is called, 29 control of the URB is returned to the device driver which issued the 30 request. The completion handler may then immediately free or reuse that 31 URB. 32 </p><p> 33 34 With few exceptions, USB device drivers should never access URB fields 35 provided by usbcore or the HCD until its <code class="function">complete</code> is called. 36 The exceptions relate to periodic transfer scheduling. For both 37 interrupt and isochronous urbs, as part of successful URB submission 38 urb->interval is modified to reflect the actual transfer period used 39 (normally some power of two units). And for isochronous urbs, 40 urb->start_frame is modified to reflect when the URB's transfers were 41 scheduled to start. 42 </p><p> 43 44 Not all isochronous transfer scheduling policies will work, but most 45 host controller drivers should easily handle ISO queues going from now 46 until 10-200 msec into the future. Drivers should try to keep at 47 least one or two msec of data in the queue; many controllers require 48 that new transfers start at least 1 msec in the future when they are 49 added. If the driver is unable to keep up and the queue empties out, 50 the behavior for new submissions is governed by the URB_ISO_ASAP flag. 51 If the flag is set, or if the queue is idle, then the URB is always 52 assigned to the first available (and not yet expired) slot in the 53 endpoint's schedule. If the flag is not set and the queue is active 54 then the URB is always assigned to the next slot in the schedule 55 following the end of the endpoint's previous URB, even if that slot is 56 in the past. When a packet is assigned in this way to a slot that has 57 already expired, the packet is not transmitted and the corresponding 58 usb_iso_packet_descriptor's status field will return -EXDEV. If this 59 would happen to all the packets in the URB, submission fails with a 60 -EXDEV error code. 61 </p><p> 62 63 For control endpoints, the synchronous <code class="function">usb_control_msg</code> call is 64 often used (in non-interrupt context) instead of this call. 65 That is often used through convenience wrappers, for the requests 66 that are standardized in the USB 2.0 specification. For bulk 67 endpoints, a synchronous <code class="function">usb_bulk_msg</code> call is available. 68</p></div><div class="refsect1"><a name="idp1115988772"></a><h2>Return</h2><p> 69 0 on successful submissions. A negative error number otherwise. 70</p></div><div class="refsect1"><a name="idp1115989428"></a><h2>Request Queuing</h2><p> 71 </p><p> 72 73 URBs may be submitted to endpoints before previous ones complete, to 74 minimize the impact of interrupt latencies and system overhead on data 75 throughput. With that queuing policy, an endpoint's queue would never 76 be empty. This is required for continuous isochronous data streams, 77 and may also be required for some kinds of interrupt transfers. Such 78 queuing also maximizes bandwidth utilization by letting USB controllers 79 start work on later requests before driver software has finished the 80 completion processing for earlier (successful) requests. 81 </p><p> 82 83 As of Linux 2.6, all USB endpoint transfer queues support depths greater 84 than one. This was previously a HCD-specific behavior, except for ISO 85 transfers. Non-isochronous endpoint queues are inactive during cleanup 86 after faults (transfer errors or cancellation). 87</p></div><div class="refsect1"><a name="idp1115991132"></a><h2>Reserved Bandwidth Transfers</h2><p> 88 </p><p> 89 90 Periodic transfers (interrupt or isochronous) are performed repeatedly, 91 using the interval specified in the urb. Submitting the first urb to 92 the endpoint reserves the bandwidth necessary to make those transfers. 93 If the USB subsystem can't allocate sufficient bandwidth to perform 94 the periodic request, submitting such a periodic request should fail. 95 </p><p> 96 97 For devices under xHCI, the bandwidth is reserved at configuration time, or 98 when the alt setting is selected. If there is not enough bus bandwidth, the 99 configuration/alt setting request will fail. Therefore, submissions to 100 periodic endpoints on devices under xHCI should never fail due to bandwidth 101 constraints. 102 </p><p> 103 104 Device drivers must explicitly request that repetition, by ensuring that 105 some URB is always on the endpoint's queue (except possibly for short 106 periods during completion callbacks). When there is no longer an urb 107 queued, the endpoint's bandwidth reservation is canceled. This means 108 drivers can use their completion handlers to ensure they keep bandwidth 109 they need, by reinitializing and resubmitting the just-completed urb 110 until the driver longer needs that periodic bandwidth. 111</p></div><div class="refsect1"><a name="idp1115993364"></a><h2>Memory Flags</h2><p> 112 </p><p> 113 114 The general rules for how to decide which mem_flags to use 115 are the same as for kmalloc. There are four 116 different possible values; GFP_KERNEL, GFP_NOFS, GFP_NOIO and 117 GFP_ATOMIC. 118 </p><p> 119 120 GFP_NOFS is not ever used, as it has not been implemented yet. 121 </p><p> 122 123 GFP_ATOMIC is used when 124 (a) you are inside a completion handler, an interrupt, bottom half, 125 tasklet or timer, or 126 (b) you are holding a spinlock or rwlock (does not apply to 127 semaphores), or 128 (c) current->state != TASK_RUNNING, this is the case only after 129 you've changed it. 130 </p><p> 131 132 GFP_NOIO is used in the block io path and error handling of storage 133 devices. 134 </p><p> 135 136 All other situations use GFP_KERNEL. 137 </p><p> 138 139 Some more specific rules for mem_flags can be inferred, such as 140 (1) start_xmit, timeout, and receive methods of network drivers must 141 use GFP_ATOMIC (they are called with a spinlock held); 142 (2) queuecommand methods of scsi drivers must use GFP_ATOMIC (also 143 called with a spinlock held); 144 (3) If you use a kernel thread with a network driver you must use 145 GFP_NOIO, unless (b) or (c) apply; 146 (4) after you have done a <code class="function">down</code> you can use GFP_KERNEL, unless (b) or (c) 147 apply or your are in a storage driver's block io path; 148 (5) USB probe and disconnect can use GFP_KERNEL unless (b) or (c) apply; and 149 (6) changing firmware on a running storage or net device uses 150 GFP_NOIO, unless b) or c) apply 151</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-unanchor-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-unlink-urb.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="phrase">usb_unanchor_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_unlink_urb</span></td></tr></table></div></body></html> 152