.\" 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_EP_QUEUE" "9" "17 July 2003" "" ""

.SH NAME
usb_ep_queue \- queues (submits) an I/O request to an endpoint.
.SH SYNOPSIS
.sp
\fB
.sp
int usb_ep_queue  (struct usb_ep * \fIep\fB, struct usb_request * \fIreq\fB, int \fIgfp_flags\fB);
\fR
.SH "ARGUMENTS"
.TP
\fB\fIep\fB\fR
the endpoint associated with the request
.TP
\fB\fIreq\fB\fR
the request being submitted
.TP
\fB\fIgfp_flags\fB\fR
GFP_* flags to use in case the lower level driver couldn't
pre-allocate all necessary memory with the request.
.SH "DESCRIPTION"
.PP
This tells the device controller to perform the specified request through
that endpoint (reading or writing a buffer).  When the request completes,
including being canceled by \fBusb_ep_dequeue\fR, the request's completion
routine is called to return the request to the driver.  Any endpoint
(except control endpoints like ep0) may have more than one transfer
request queued; they complete in FIFO order.  Once a gadget driver
submits a request, that request may not be examined or modified until it
is given back to that driver through the completion callback.
.PP
Each request is turned into one or more packets.  The controller driver
never merges adjacent requests into the same packet.  OUT transfers
will sometimes use data that's already buffered in the hardware.
.PP
Bulk endpoints can queue any amount of data; the transfer is packetized
automatically.  The last packet will be short if the request doesn't fill it
out completely.  Zero length packets (ZLPs) should be avoided in portable
protocols since not all usb hardware can successfully handle zero length
packets.  (ZLPs may be explicitly written, and may be implicitly written if
the request 'zero' flag is set.)  Bulk endpoints may also be used
for interrupt transfers; but the reverse is not true, and some endpoints
won't support every interrupt transfer.  (Such as 768 byte packets.)
.PP
Interrupt-only endpoints are less functional than bulk endpoints, for
example by not supporting queueing or not handling buffers that are
larger than the endpoint's maxpacket size.  They may also treat data
toggle differently.
.PP
Control endpoints ... after getting a \fBsetup\fR callback, the driver queues
one response (optional if it would be zero length).  That enables the
status ack, after transfering data as specified in the response.  Setup
functions may return negative error codes to generate protocol stalls.
.PP
For periodic endpoints, like interrupt or isochronous ones, the usb host
arranges to poll once per interval, and the gadget driver usually will
have queued some data to transfer at that time.
.PP
Returns zero, or a negative error code.  Endpoints that are not enabled,
or which are enabled but halted, report errors; errors will also be
reported when the usb peripheral is disconnected.
.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.5.74.