.\" This documentation was generated from the book titled "USB Gadget API for Linux", which is part of the Linux kernel source. .\" .\" This documentation comes with the following legal notice: .\" .\" 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. .\" .\" 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. .\" .\" 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 .\" .\" For more details see the file COPYING in the source .\" distribution of Linux. .\" .\" For comments on the formatting of this manpage, please contact Michael Still .\" This manpage has been automatically generated by docbook2man .\" from a DocBook document. This tool can be found at: .\" .\" Please send any bug reports, improvements, comments, patches, .\" etc. to Steve Cheng . .TH "USB_REQUEST" "9" "09 April 2004" "" "" .SH NAME struct usb_request \- describes one i/o request .SH SYNOPSIS .nf 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; }; .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 \fBno_interrupt\fR If true, hints that no completion irq is needed. Helpful sometimes with deep request queues. .TP \fBzero\fR If true, when writing data, makes the last packet be ``short'' by adding a zero length packet as needed; .TP \fBshort_not_ok\fR When reading data, makes short packets be treated as errors (queue stops advancing till cleanup). .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 This documentation was generated with kernel version 2.6.0.