.\" 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 "URB" "9" "17 July 2003" "" ""
.SH NAME
struct urb \- USB Request Block
.SH SYNOPSIS
.nf
struct urb {
struct list_head urb_list;
struct usb_device * dev;
unsigned int pipe;
int status;
unsigned int transfer_flags;
void * transfer_buffer;
dma_addr_t transfer_dma;
int transfer_buffer_length;
int actual_length;
unsigned char * setup_packet;
dma_addr_t setup_dma;
int start_frame;
int number_of_packets;
int interval;
int error_count;
void * context;
usb_complete_t complete;
struct usb_iso_packet_descriptor * iso_frame_desc;
};
.fi
.SH "MEMBERS"
.TP
\fBurb_list\fR
For use by current owner of the URB.
.TP
\fBdev\fR
Identifies the USB device to perform the request.
.TP
\fBpipe\fR
Holds endpoint number, direction, type, and more.
Create these values with the eight macros available;
usb_{snd,rcv}TYPEpipe(dev,endpoint), where the type is ``ctrl''
(control), ``bulk'', ``int'' (interrupt), or ``iso'' (isochronous).
For example \fBusb_sndbulkpipe\fR or \fBusb_rcvintpipe\fR. Endpoint
numbers range from zero to fifteen. Note that ``in'' endpoint two
is a different endpoint (and pipe) from ``out'' endpoint two.
The current configuration controls the existence, type, and
maximum packet size of any given endpoint.
.TP
\fBstatus\fR
This is read in non-iso completion functions to get the
status of the particular request. ISO requests only use it
to tell whether the URB was unlinked; detailed status for
each frame is in the fields of the iso_frame-desc.
.TP
\fBtransfer_flags\fR
A variety of flags may be used to affect how URB
submission, unlinking, or operation are handled. Different
kinds of URB can use different flags.
.TP
\fBtransfer_buffer\fR
This identifies the buffer to (or from) which
the I/O request will be performed (unless URB_NO_TRANSFER_DMA_MAP
is set). This buffer must be suitable for DMA; allocate it with
\fBkmalloc\fR or equivalent. For transfers to ``in'' endpoints, contents
of this buffer will be modified. This buffer is used for data
phases of control transfers.
.TP
\fBtransfer_dma\fR
When transfer_flags includes URB_NO_TRANSFER_DMA_MAP,
the device driver is saying that it provided this DMA address,
which the host controller driver should use in preference to the
transfer_buffer.
.TP
\fBtransfer_buffer_length\fR
How big is transfer_buffer. The transfer may
be broken up into chunks according to the current maximum packet
size for the endpoint, which is a function of the configuration
and is encoded in the pipe. When the length is zero, neither
transfer_buffer nor transfer_dma is used.
.TP
\fBactual_length\fR
This is read in non-iso completion functions, and
it tells how many bytes (out of transfer_buffer_length) were
transferred. It will normally be the same as requested, unless
either an error was reported or a short read was performed.
The URB_SHORT_NOT_OK transfer flag may be used to make such
short reads be reported as errors.
.TP
\fBsetup_packet\fR
Only used for control transfers, this points to eight bytes
of setup data. Control transfers always start by sending this data
to the device. Then transfer_buffer is read or written, if needed.
.TP
\fBsetup_dma\fR
For control transfers with URB_NO_SETUP_DMA_MAP set, the
device driver has provided this DMA address for the setup packet.
The host controller driver should use this in preference to
setup_packet.
.TP
\fBstart_frame\fR
Returns the initial frame for interrupt or isochronous
transfers.
.TP
\fBnumber_of_packets\fR
Lists the number of ISO transfer buffers.
.TP
\fBinterval\fR
Specifies the polling interval for interrupt or isochronous
transfers. The units are frames (milliseconds) for for full and low
speed devices, and microframes (1/8 millisecond) for highspeed ones.
.TP
\fBerror_count\fR
Returns the number of ISO transfers that reported errors.
.TP
\fBcontext\fR
For use in completion functions. This normally points to
request-specific driver context.
.TP
\fBcomplete\fR
Completion handler. This URB is passed as the parameter to the
completion function. The completion function may then do what
it likes with the URB, including resubmitting or freeing it.
.TP
\fBiso_frame_desc\fR
Used to provide arrays of ISO transfer buffers and to
collect the transfer status for each buffer.
.SH "DESCRIPTION"
.PP
This structure identifies USB transfer requests. URBs must be allocated by
calling \fBusb_alloc_urb\fR and freed with a call to \fBusb_free_urb\fR.
Initialization may be done using various usb_fill_*\fB_urb\fR functions. URBs
are submitted using \fBusb_submit_urb\fR, and pending requests may be canceled
using \fBusb_unlink_urb\fR.
.SH "DATA TRANSFER BUFFERS"
.PP
.PP
Normally drivers provide I/O buffers allocated with \fBkmalloc\fR or otherwise
taken from the general page pool. That is provided by transfer_buffer
(control requests also use setup_packet), and host controller drivers
perform a dma mapping (and unmapping) for each buffer transferred. Those
mapping operations can be expensive on some platforms (perhaps using a dma
bounce buffer or talking to an IOMMU),
although they're cheap on commodity x86 and ppc hardware.
.PP
Alternatively, drivers may pass the URB_NO_xxx_DMA_MAP transfer flags,
which tell the host controller driver that no such mapping is needed since
the device driver is DMA-aware. For example, a device driver might
allocate a DMA buffer with \fBusb_buffer_alloc\fR or call \fBusb_buffer_map\fR.
When these transfer flags are provided, host controller drivers will
attempt to use the dma addresses found in the transfer_dma and/or
setup_dma fields rather than determining a dma address themselves. (Note
that transfer_buffer and setup_packet must still be set because not all
host controllers use DMA, nor do virtual root hubs).
.SH "INITIALIZATION"
.PP
.PP
All URBs submitted must initialize dev, pipe,
transfer_flags (may be zero), complete, timeout (may be zero).
The URB_ASYNC_UNLINK transfer flag affects later invocations of
the \fBusb_unlink_urb\fR routine.
.PP
All URBs must also initialize
transfer_buffer and transfer_buffer_length. They may provide the
URB_SHORT_NOT_OK transfer flag, indicating that short reads are
to be treated as errors; that flag is invalid for write requests.
.PP
Bulk URBs may
use the URB_ZERO_PACKET transfer flag, indicating that bulk OUT transfers
should always terminate with a short packet, even if it means adding an
extra zero length packet.
.PP
Control URBs must provide a setup_packet. The setup_packet and
transfer_buffer may each be mapped for DMA or not, independently of
the other. The transfer_flags bits URB_NO_TRANSFER_DMA_MAP and
URB_NO_SETUP_DMA_MAP indicate which buffers have already been mapped.
URB_NO_SETUP_DMA_MAP is ignored for non-control URBs.
.PP
Interrupt UBS must provide an interval, saying how often (in milliseconds
or, for highspeed devices, 125 microsecond units)
to poll for transfers. After the URB has been submitted, the interval
and start_frame fields reflect how the transfer was actually scheduled.
The polling interval may be more frequent than requested.
For example, some controllers have a maximum interval of 32 microseconds,
while others support intervals of up to 1024 microseconds.
Isochronous URBs also have transfer intervals. (Note that for isochronous
endpoints, as well as high speed interrupt endpoints, the encoding of
the transfer interval in the endpoint descriptor is logarithmic.)
.PP
Isochronous URBs normally use the URB_ISO_ASAP transfer flag, telling
the host controller to schedule the transfer as soon as bandwidth
utilization allows, and then set start_frame to reflect the actual frame
selected during submission. Otherwise drivers must specify the start_frame
and handle the case where the transfer can't begin then. However, drivers
won't know how bandwidth is currently allocated, and while they can
find the current frame using usb_get_current_frame_number () they can't
know the range for that frame number. (Ranges for frame counter values
are HC-specific, and can go from 256 to 65536 frames from ``now''.)
.PP
Isochronous URBs have a different data transfer model, in part because
the quality of service is only ``best effort''. Callers provide specially
allocated URBs, with number_of_packets worth of iso_frame_desc structures
at the end. Each such packet is an individual ISO transfer. Isochronous
URBs are normally queued, submitted by drivers to arrange that
transfers are at least double buffered, and then explicitly resubmitted
in completion handlers, so
that data (such as audio or video) streams at as constant a rate as the
host controller scheduler can support.
.SH "COMPLETION CALLBACKS"
.PP
.PP
The completion callback is made \fBin_interrupt\fR, and one of the first
things that a completion handler should do is check the status field.
The status field is provided for all URBs. It is used to report
unlinked URBs, and status for all non-ISO transfers. It should not
be examined before the URB is returned to the completion handler.
.PP
The context field is normally used to link URBs back to the relevant
driver or request state.
.PP
When completion callback is invoked for non-isochronous URBs, the
actual_length field tells how many bytes were transferred.
.PP
ISO transfer status is reported in the status and actual_length fields
of the iso_frame_desc array, and the number of errors is reported in
error_count. Completion callbacks for ISO transfers will normally
(re)submit URBs to ensure a constant transfer rate.
.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.