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

.SH NAME
struct usb_request \- describes one i/o request
.SH SYNOPSIS

.nf
struct usb_request {
  void * buf;
  unsigned length;
  dma_addr_t dma;
  void (* complete (struct usb_ep *ep,struct usb_request *req);
  void * context;
  struct list_head list;
  int status;
  unsigned actual;
};  
.fi
.SH "MEMBERS"
.TP
\fBbuf\fR
Buffer used for data.  Always provide this; some controllers
only use PIO, or don't use DMA for some endpoints.
.TP
\fBlength\fR
Length of that data
.TP
\fBdma\fR
DMA address corresponding to 'buf'.  If you don't set this
field, and the usb controller needs one, it is responsible
for mapping and unmapping the buffer.
.TP
\fBcomplete\fR
Function called when request completes
.TP
\fBcontext\fR
For use by the completion callback
.TP
\fBlist\fR
For use by the gadget driver.
.TP
\fBstatus\fR
Reports completion code, zero or a negative errno.
Normally, faults block the transfer queue from advancing until
the completion callback returns.
Code ``-ESHUTDOWN'' indicates completion caused by device disconnect,
or when the driver disabled the endpoint.
.TP
\fBactual\fR
Reports actual bytes transferred.  For reads (OUT
transfers) this may be less than the requested length.  If the
short_not_ok flag is set, short reads are treated as errors
even when status otherwise indicates successful completion.
Note that for writes (IN transfers) the data bytes may still
reside in a device-side FIFO.
.SH "DESCRIPTION"
.PP
These are allocated/freed through the endpoint they're used with.  The
hardware's driver can add extra per-request data to the memory it returns,
which often avoids separate memory allocations (potential failures),
later when the request is queued.
.PP
Request flags affect request handling, such as whether a zero length
packet is written (the ``zero'' flag), whether a short read should be
treated as an error (blocking request queue advance, the ``short_not_ok''
flag), or hinting that an interrupt is not required (the ``no_interrupt''
flag, for use with deep request queues).
.PP
Bulk endpoints can use any size buffers, and can also be used for interrupt
transfers. interrupt-only endpoints can be much less functional.
.SH "ABOUT THIS DOCUMENT"
.PP
Permission is granted to copy, distribute, and/or modify
this document under the terms of the GNU Free Documentation
License, version 1.2, or any later version published by the
Free Software Foundation; with the Invariant Sections being
the "GNU Free Documentation License",
no Front-Cover Texts,
and
no Back-Cover Texts.
.PP
This documentation 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 Free Documentation License for more details.
.PP
Note that certain sections of this document are merged
into Linux kernel source code.
That content is the bulk of 
[XRef to CORE]> and
[XRef to UTILS]>,
where the "GNU Free Documentation License" is identified
as an alternate licence for its documentation.
.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.72.