1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>usb_ep_queue</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="USB Gadget API for Linux"><link rel="up" href="core.html" title="Core Objects and Methods"><link rel="prev" href="API-usb-ep-free-request.html" title="usb_ep_free_request"><link rel="next" href="API-usb-ep-dequeue.html" title="usb_ep_dequeue"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center"><span class="phrase">usb_ep_queue</span></th></tr><tr><td width="20%" align="left"><a accesskey="p" href="API-usb-ep-free-request.html">Prev</a> </td><th width="60%" align="center">Core Objects and Methods</th><td width="20%" align="right"> <a accesskey="n" href="API-usb-ep-dequeue.html">Next</a></td></tr></table><hr></div><div class="refentry"><a name="API-usb-ep-queue"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>usb_ep_queue — 2 queues (submits) an I/O request to an endpoint. 3 </p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">usb_ep_queue </b>(</code></td><td>struct usb_ep * <var class="pdparam">ep</var>, </td></tr><tr><td> </td><td>struct usb_request * <var class="pdparam">req</var>, </td></tr><tr><td> </td><td>gfp_t <var class="pdparam">gfp_flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idp1124000908"></a><h2>Arguments</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="parameter"><code>ep</code></em></span></dt><dd><p> 4 the endpoint associated with the request 5 </p></dd><dt><span class="term"><em class="parameter"><code>req</code></em></span></dt><dd><p> 6 the request being submitted 7 </p></dd><dt><span class="term"><em class="parameter"><code>gfp_flags</code></em></span></dt><dd><p> 8 GFP_* flags to use in case the lower level driver couldn't 9 pre-allocate all necessary memory with the request. 10 </p></dd></dl></div></div><div class="refsect1"><a name="idp1124004580"></a><h2>Description</h2><p> 11 This tells the device controller to perform the specified request through 12 that endpoint (reading or writing a buffer). When the request completes, 13 including being canceled by <code class="function">usb_ep_dequeue</code>, the request's completion 14 routine is called to return the request to the driver. Any endpoint 15 (except control endpoints like ep0) may have more than one transfer 16 request queued; they complete in FIFO order. Once a gadget driver 17 submits a request, that request may not be examined or modified until it 18 is given back to that driver through the completion callback. 19 </p><p> 20 21 Each request is turned into one or more packets. The controller driver 22 never merges adjacent requests into the same packet. OUT transfers 23 will sometimes use data that's already buffered in the hardware. 24 Drivers can rely on the fact that the first byte of the request's buffer 25 always corresponds to the first byte of some USB packet, for both 26 IN and OUT transfers. 27 </p><p> 28 29 Bulk endpoints can queue any amount of data; the transfer is packetized 30 automatically. The last packet will be short if the request doesn't fill it 31 out completely. Zero length packets (ZLPs) should be avoided in portable 32 protocols since not all usb hardware can successfully handle zero length 33 packets. (ZLPs may be explicitly written, and may be implicitly written if 34 the request 'zero' flag is set.) Bulk endpoints may also be used 35 for interrupt transfers; but the reverse is not true, and some endpoints 36 won't support every interrupt transfer. (Such as 768 byte packets.) 37 </p><p> 38 39 Interrupt-only endpoints are less functional than bulk endpoints, for 40 example by not supporting queueing or not handling buffers that are 41 larger than the endpoint's maxpacket size. They may also treat data 42 toggle differently. 43 </p><p> 44 45 Control endpoints ... after getting a <code class="function">setup</code> callback, the driver queues 46 one response (even if it would be zero length). That enables the 47 status ack, after transferring data as specified in the response. Setup 48 functions may return negative error codes to generate protocol stalls. 49 (Note that some USB device controllers disallow protocol stall responses 50 in some cases.) When control responses are deferred (the response is 51 written after the setup callback returns), then <code class="function">usb_ep_set_halt</code> may be 52 used on ep0 to trigger protocol stalls. Depending on the controller, 53 it may not be possible to trigger a status-stage protocol stall when the 54 data stage is over, that is, from within the response's completion 55 routine. 56 </p><p> 57 58 For periodic endpoints, like interrupt or isochronous ones, the usb host 59 arranges to poll once per interval, and the gadget driver usually will 60 have queued some data to transfer at that time. 61 </p><p> 62 63 Returns zero, or a negative error code. Endpoints that are not enabled 64 report errors; errors will also be 65 reported when the usb peripheral is disconnected. 66</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-ep-free-request.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="core.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="API-usb-ep-dequeue.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="phrase">usb_ep_free_request</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> <span class="phrase">usb_ep_dequeue</span></td></tr></table></div></body></html> 67