<?xml version="1.0" encoding="ANSI_X3.4-1968" standalone="no"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"><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.76.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><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center"><span>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" title="usb_submit_urb"><a id="API-usb-submit-urb"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>usb_submit_urb — issue an asynchronous transfer request for an endpoint </p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">int <strong>fsfuncusb_submit_urb </strong>(</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" title="Arguments"><a id="id2985103"></a><h2>Arguments</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>urb</code></em></span></dt><dd><p> pointer to the urb describing the request </p></dd><dt><span class="term"><em class="parameter"><code>mem_flags</code></em></span></dt><dd><p> the type of memory to allocate, see <code class="function">kmalloc</code> for a list of valid options for this. </p></dd></dl></div></div><div class="refsect1" title="Description"><a id="id2985152"></a><h2>Description</h2><p> This submits a transfer request, and transfers control of the URB describing that request to the USB subsystem. Request completion will be indicated later, asynchronously, by calling the completion handler. The three types of completion are success, error, and unlink (a software-induced fault, also called <span class="quote">“<span class="quote">request cancellation</span>”</span>). </p><p> URBs may be submitted in interrupt context. </p><p> The caller must have correctly initialized the URB before submitting it. Functions such as <code class="function">usb_fill_bulk_urb</code> and <code class="function">usb_fill_control_urb</code> are available to ensure that most fields are correctly initialized, for the particular kind of transfer, although they will not initialize any transfer flags. </p><p> Successful submissions return 0; otherwise this routine returns a negative error number. If the submission is successful, the <code class="function">complete</code> callback from the URB will be called exactly once, when the USB core and Host Controller Driver (HCD) are finished with the URB. When the completion function is called, control of the URB is returned to the device driver which issued the request. The completion handler may then immediately free or reuse that URB. </p><p> With few exceptions, USB device drivers should never access URB fields provided by usbcore or the HCD until its <code class="function">complete</code> is called. The exceptions relate to periodic transfer scheduling. For both interrupt and isochronous urbs, as part of successful URB submission urb->interval is modified to reflect the actual transfer period used (normally some power of two units). And for isochronous urbs, urb->start_frame is modified to reflect when the URB's transfers were scheduled to start. Not all isochronous transfer scheduling policies will work, but most host controller drivers should easily handle ISO queues going from now until 10-200 msec into the future. </p><p> For control endpoints, the synchronous <code class="function">usb_control_msg</code> call is often used (in non-interrupt context) instead of this call. That is often used through convenience wrappers, for the requests that are standardized in the USB 2.0 specification. For bulk endpoints, a synchronous <code class="function">usb_bulk_msg</code> call is available. </p></div><div class="refsect1" title="Request Queuing"><a id="id2985253"></a><h2>Request Queuing</h2><p> </p><p> URBs may be submitted to endpoints before previous ones complete, to minimize the impact of interrupt latencies and system overhead on data throughput. With that queuing policy, an endpoint's queue would never be empty. This is required for continuous isochronous data streams, and may also be required for some kinds of interrupt transfers. Such queuing also maximizes bandwidth utilization by letting USB controllers start work on later requests before driver software has finished the completion processing for earlier (successful) requests. </p><p> As of Linux 2.6, all USB endpoint transfer queues support depths greater than one. This was previously a HCD-specific behavior, except for ISO transfers. Non-isochronous endpoint queues are inactive during cleanup after faults (transfer errors or cancellation). </p></div><div class="refsect1" title="Reserved Bandwidth Transfers"><a id="id2985282"></a><h2>Reserved Bandwidth Transfers</h2><p> </p><p> Periodic transfers (interrupt or isochronous) are performed repeatedly, using the interval specified in the urb. Submitting the first urb to the endpoint reserves the bandwidth necessary to make those transfers. If the USB subsystem can't allocate sufficient bandwidth to perform the periodic request, submitting such a periodic request should fail. </p><p> For devices under xHCI, the bandwidth is reserved at configuration time, or when the alt setting is selected. If there is not enough bus bandwidth, the configuration/alt setting request will fail. Therefore, submissions to periodic endpoints on devices under xHCI should never fail due to bandwidth constraints. </p><p> Device drivers must explicitly request that repetition, by ensuring that some URB is always on the endpoint's queue (except possibly for short periods during completion callacks). When there is no longer an urb queued, the endpoint's bandwidth reservation is canceled. This means drivers can use their completion handlers to ensure they keep bandwidth they need, by reinitializing and resubmitting the just-completed urb until the driver longer needs that periodic bandwidth. </p></div><div class="refsect1" title="Memory Flags"><a id="id2985325"></a><h2>Memory Flags</h2><p> </p><p> The general rules for how to decide which mem_flags to use are the same as for kmalloc. There are four different possible values; GFP_KERNEL, GFP_NOFS, GFP_NOIO and GFP_ATOMIC. </p><p> GFP_NOFS is not ever used, as it has not been implemented yet. </p><p> GFP_ATOMIC is used when (a) you are inside a completion handler, an interrupt, bottom half, tasklet or timer, or (b) you are holding a spinlock or rwlock (does not apply to semaphores), or (c) current->state != TASK_RUNNING, this is the case only after you've changed it. </p><p> GFP_NOIO is used in the block io path and error handling of storage devices. </p><p> All other situations use GFP_KERNEL. </p><p> Some more specific rules for mem_flags can be inferred, such as (1) start_xmit, timeout, and receive methods of network drivers must use GFP_ATOMIC (they are called with a spinlock held); (2) queuecommand methods of scsi drivers must use GFP_ATOMIC (also called with a spinlock held); (3) If you use a kernel thread with a network driver you must use GFP_NOIO, unless (b) or (c) apply; (4) after you have done a <code class="function">down</code> you can use GFP_KERNEL, unless (b) or (c) apply or your are in a storage driver's block io path; (5) USB probe and disconnect can use GFP_KERNEL unless (b) or (c) apply; and (6) changing firmware on a running storage or net device uses GFP_NOIO, unless b) or c) apply </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>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>usb_unlink_urb</span></td></tr></table></div></body></html>