Name

struct urb — USB Request Block

Members

urb_list

For use by current owner of the URB.

anchor_list

membership in the list of an anchor

anchor

to anchor URBs to a common mooring

dev

Identifies the USB device to perform the request.

ep

Points to the endpoint's data structure. Will eventually replace pipe.

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.

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.