int usb_submit_urb (struct urb * urb, int mem_flags);
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.
The caller must have correctly initialized the URB before submitting it. Functions such as usb_fill_bulk_urb and usb_fill_control_urb are available to ensure that most fields are correctly initialized, for the particular kind of transfer, although they will not initialize any transfer flags.
Successful submissions return 0; otherwise this routine returns a negative error number. If the submission is successful, the complete 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.
For control endpoints, the synchronous usb_control_msg 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 usb_bulk_msg call is available.
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.
Bulk and Isochronous URBs may always be queued. At this writing, all mainstream host controller drivers support queueing for control and interrupt transfer requests.
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.
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.
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.
GFP_NOFS is not ever used, as it has not been implemented yet.
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.
GFP_NOIO is used in the block io path and error handling of storage devices.
All other situations use GFP_KERNEL.
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 down 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
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.
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.
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
For more details see the file COPYING in the source distribution of Linux.
If you have comments on the formatting of this manpage, then please contact Michael Still (mikal@stillhq.com).
This documentation was generated with kernel version 2.5.71.