<?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.75.2" /><link rel="home" href="index.html" title="The Linux-USB Host Side API" /><link rel="up" href="ch05.html" title="Chapter 5. USB Core APIs" /><link rel="prev" href="re46.html" title="usb_unanchor_urb" /><link rel="next" href="re48.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="re46.html">Prev</a> </td><th width="60%" align="center">Chapter 5. USB Core APIs</th><td width="20%" align="right"> <a accesskey="n" href="re48.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 <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" title="Arguments"><a id="id2744103"></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="id2744153"></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="id2744254"></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="id2744283"></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="id2744320"></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="re46.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch05.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="re48.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>
