Provided by:
linux-doc-2.6.15_2.6.15-23.39_all 
NAME
struct urb - USB Request Block
SYNOPSIS
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[0];
};
MEMBERS
urb_list
For use by current owner of the URB.
dev Identifies the USB device to perform the request.
pipe 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 usb_sndbulkpipe or usb_rcvintpipe.
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.
status 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.
transfer_flags
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.
transfer_buffer
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 kmalloc or
equivalent. For transfers to ‘‘in’’ endpoints, contents of this
buffer will be modified. This buffer is used for the data stage
of control transfers.
transfer_dma
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.
transfer_buffer_length
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.
actual_length
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.
setup_packet
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.
setup_dma
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.
start_frame
Returns the initial frame for isochronous transfers.
number_of_packets
Lists the number of ISO transfer buffers.
interval
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.
error_count
Returns the number of ISO transfers that reported errors.
context
For use in completion functions. This normally points to
request-specific driver context.
complete
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.
iso_frame_desc[0]
Used to provide arrays of ISO transfer buffers and to collect
the transfer status for each buffer.
DESCRIPTION
This structure identifies USB transfer requests. URBs must be allocated
by calling usb_alloc_urb and freed with a call to usb_free_urb.
Initialization may be done using various usb_fill_*_urb functions. URBs
are submitted using usb_submit_urb, and pending requests may be
canceled using usb_unlink_urb or usb_kill_urb.
DATA TRANSFER BUFFERS
Normally drivers provide I/O buffers allocated with kmalloc 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.
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 usb_buffer_alloc or call
usb_buffer_map. 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).
INITIALIZATION
All URBs submitted must initialize the dev, pipe, transfer_flags (may
be zero), and complete fields. 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.
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.
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.
Interrupt URBs 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 field
reflects 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 milliseconds, while others support intervals
of up to 1024 milliseconds. 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. Device drivers must convert that
value to linear units themselves.)
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’’.)
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.
COMPLETION CALLBACKS
The completion callback is made in_interrupt, 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.
The context field is normally used to link URBs back to the relevant
driver or request state.
When the completion callback is invoked for non-isochronous URBs, the
actual_length field tells how many bytes were transferred. This field
is updated even when the URB terminated with an error or was unlinked.
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.
Note that even fields marked ‘‘public’’ should not be touched by the
driver when the urb is owned by the hcd, that is, since the call to
usb_submit_urb till the entry into the completion routine.