Provided by:
linux-doc-2.6.15_2.6.15-23.39_all 
NAME
struct usb_request - describes one i/o request
SYNOPSIS
struct usb_request {
void * buf;
unsigned length;
dma_addr_t dma;
unsigned no_interrupt:1;
unsigned zero:1;
unsigned short_not_ok:1;
void (* complete) (struct usb_ep *ep,struct usb_request *req);
void * context;
struct list_head list;
int status;
unsigned actual;
};
MEMBERS
buf Buffer used for data. Always provide this; some controllers only
use PIO, or don’t use DMA for some endpoints.
length Length of that data
dma 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.
no_interrupt
If true, hints that no completion irq is needed. Helpful
sometimes with deep request queues that are handled directly by
DMA controllers.
zero If true, when writing data, makes the last packet be ‘‘short’’
by adding a zero length packet as needed;
short_not_ok
When reading data, makes short packets be treated as errors
(queue stops advancing till cleanup).
complete
Function called when request completes, so this request and its
buffer may be re-used. Reads terminate with a short packet, or
when the buffer fills, whichever comes first. When writes
terminate, some data bytes will usually still be in flight
(often in a hardware fifo). Errors (for reads or writes) stop
the queue from advancing until the completion function returns,
so that any transfers invalidated by the error may first be
dequeued.
context
For use by the completion callback
list For use by the gadget driver.
status 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.
actual Reports bytes transferred to/from the buffer. 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) some data bytes may still reside in a
device-side FIFO when the request is reported as complete.
DESCRIPTION
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.
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).
Bulk endpoints can use any size buffers, and can also be used for
interrupt transfers. interrupt-only endpoints can be much less
functional.
AUTHOR
David Brownell <dbrownell@users.sourceforge.net>.