'\" t .\" Title: usb_submit_urb .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] .\" Generator: DocBook XSL Stylesheets v1.79.1 .\" Date: January 2017 .\" Manual: USB Core APIs .\" Source: Kernel Hackers Manual 4.8.15 .\" Language: English .\" .TH "USB_SUBMIT_URB" "9" "January 2017" "Kernel Hackers Manual 4\&.8\&." "USB Core APIs" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" usb_submit_urb \- issue an asynchronous transfer request for an endpoint .SH "SYNOPSIS" .HP \w'int\ usb_submit_urb('u .BI "int usb_submit_urb(struct\ urb\ *\ " "urb" ", gfp_t\ " "mem_flags" ");" .SH "ARGUMENTS" .PP \fIurb\fR .RS 4 pointer to the urb describing the request .RE .PP \fImem_flags\fR .RS 4 the type of memory to allocate, see \fBkmalloc\fR for a list of valid options for this\&. .RE .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 (a software\-induced fault, also called \(lqrequest cancellation\(rq)\&. .PP 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 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 (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\&. .PP With few exceptions, USB device drivers should never access URB fields provided by usbcore or the HCD until its \fBcomplete\fR 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\*(Aqs transfers were scheduled to start\&. .PP 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\&. Drivers should try to keep at least one or two msec of data in the queue; many controllers require that new transfers start at least 1 msec in the future when they are added\&. If the driver is unable to keep up and the queue empties out, the behavior for new submissions is governed by the URB_ISO_ASAP flag\&. If the flag is set, or if the queue is idle, then the URB is always assigned to the first available (and not yet expired) slot in the endpoint\*(Aqs schedule\&. If the flag is not set and the queue is active then the URB is always assigned to the next slot in the schedule following the end of the endpoint\*(Aqs previous URB, even if that slot is in the past\&. When a packet is assigned in this way to a slot that has already expired, the packet is not transmitted and the corresponding usb_iso_packet_descriptor\*(Aqs status field will return \-EXDEV\&. If this would happen to all the packets in the URB, submission fails with a \-EXDEV error code\&. .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 "RETURN" .PP 0 on successful submissions\&. A negative error number otherwise\&. .PP Request Queuing: .PP 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\*(Aqs 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\&. .PP 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)\&. .PP Reserved Bandwidth Transfers: .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\*(Aqt allocate sufficient bandwidth to perform the periodic request, submitting such a periodic request should fail\&. .PP 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\&. .PP Device drivers must explicitly request that repetition, by ensuring that some URB is always on the endpoint\*(Aqs queue (except possibly for short periods during completion callbacks)\&. When there is no longer an urb queued, the endpoint\*(Aqs 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\&. .PP Memory Flags: .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\*(Aqve 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\*(Aqs 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 "COPYRIGHT" .br