.\" This manpage has been automatically generated by docbook2man 
.\" from a DocBook document.  This tool can be found at:
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
.\" Please send any bug reports, improvements, comments, patches, 
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.TH "USB_SUBMIT_URB" "9" "07 August 2003" "" ""
.SH NAME
usb_submit_urb \- issue an asynchronous transfer request for an endpoint
.SH SYNOPSIS
.sp
\fB
.sp
int usb_submit_urb  (struct urb * \fIurb\fB, int \fImem_flags\fB);
\fR
.SH "ARGUMENTS"
.TP
\fB\fIurb\fB\fR
pointer to the urb describing the request
.TP
\fB\fImem_flags\fB\fR
the type of memory to allocate, see \fBkmalloc\fR for a list
of valid options for this.
.SH "DESCRIPTION"
.PP
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
(also called ``request cancellation'').
URBs may be submitted in interrupt context.
.PP
The caller must have correctly initialized the URB before submitting
it.  Functions such as \fBusb_fill_bulk_urb\fR and \fBusb_fill_control_urb\fR are
available to ensure that most fields are correctly initialized, for
the particular kind of transfer, although they will not initialize
any transfer flags.
.PP
Successful submissions return 0; otherwise this routine returns a
negative error number.  If the submission is successful, the \fBcomplete\fR
callback from the urb will be called exactly once, when the USB core and
host controller driver 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.
.PP
For control endpoints, the synchronous \fBusb_control_msg\fR 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 \fBusb_bulk_msg\fR call is available.
.SH "REQUEST QUEUING"
.PP
.PP
URBs may be submitted to endpoints before previous ones complete, to
minimize the impact of interrupt latencies and system overhead on data
throughput.  This is required for continuous isochronous data streams,
and may also be required for some kinds of interrupt transfers. Such
queueing also maximizes bandwidth utilization by letting USB controllers
start work on later requests before driver software has finished the
completion processing for earlier requests.
.PP
Bulk and Isochronous URBs may always be queued.  At this writing, all
mainstream host controller drivers support queueing for control and
interrupt transfer requests.
.SH "RESERVED BANDWIDTH TRANSFERS"
.PP
.PP
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.
.PP
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.
.SH "MEMORY FLAGS"
.PP
.PP
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.
.PP
GFP_NOFS is not ever used, as it has not been implemented yet.
.PP
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.
.PP
GFP_NOIO is used in the block io path and error handling of storage
devices.
.PP
All other situations use GFP_KERNEL.
.PP
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 \fBdown\fR 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
.SH "ABOUT THIS DOCUMENT"
.PP
This documentation is free software; you can redistribute
it and/or modify it under the terms of the GNU General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later
version.
.PP
This program is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
.PP
You should have received a copy of the GNU General Public
License along with this program; if not, write to the Free
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
MA 02111-1307 USA
.PP
For more details see the file COPYING in the source
distribution of Linux.
.PP
If you have comments on the formatting of this manpage, then please contact
Michael Still (mikal@stillhq.com).
.PP
This documentation was generated with kernel version 2.6.0.