Logo Search packages:      
Sourcecode: virtualbox-ose version File versions  Download package

VUSB - Virtual USB

read thru this and correct typos. Merge with old docs.
The Virtual USB component glues USB devices and host controllers together. The VUSB takes the form of a PDM driver which is attached to the HCI. USB devices are created by, attached to, and managed by the VUSB roothub. The VUSB also exposes an interface which is used by Main to attach and detach proxied USB devices.

The Life of an URB

The URB is created when the HCI calls the roothub (VUSB) method pfnNewUrb. VUSB has a pool of URBs, if no free URBs are availabe a new one is allocated. The returned URB starts life in the ALLOCATED state and all fields are initalized with sensible defaults.

The HCI then copies any request data into the URB if it's an host2dev transfer. It then submits the URB by calling the pfnSubmitUrb roothub method.

pfnSubmitUrb will start by checking if it knows the device address, and if it doesn't the URB is completed with a device-not-ready error. When the device address is known to it, action is taken based on the kind of transfer it is. There are four kinds of transfers: 1. control, 2. bulk, 3. interrupt, and 4. isochronous. In either case something eventually ends up being submitted to the device.

If an URB fails submitting, may or may not be completed. This depends on heuristics in some cases and on the kind of failure in others. If pfnSubmitUrb returns a failure, the HCI should retry submitting it at a later time. If pfnSubmitUrb returns success the URB is submitted, and it can even been completed.

The URB is in the IN_FLIGHT state from the time it's successfully submitted and till it's reaped or cancelled.

When an URB transfer or in some case submit failure occurs, the pfnXferError callback of the HCI is consulted about what to do. If pfnXferError indicates that the URB should be retried, pfnSubmitUrb will fail. If it indicates that it should fail, the URB will be completed.

Completing an URB means that the URB status is set and the HCI pfnXferCompletion callback is invoked with the URB. The HCI is the supposed to report the transfer status to the guest OS. After completion the URB is freed and returned to the pool, unless it was cancelled. If it was cancelled it will have to await reaping before it's actually freed.


The control transfer is the most complex one, from VUSB's point of view, with its three stages and being bi-directional. A control transfer starts with a SETUP packet containing the request description and two basic parameters. It is followed by zero or more DATA packets which either picks up incoming data (dev2host) or supplies the request data (host2dev). This can then be followed by a STATUS packet which gets the status of the whole transfer.

What makes the control transfer complicated is that for a host2dev request the URB is assembled from the SETUP and DATA stage, and for a dev2host request the returned data must be kept around for the DATA stage. For both transfer directions the status of the transfer has to be kept around for the STATUS stage.

To complicate matters futher, VUSB must intercept and in some cases emulate some of the standard requests in order to keep the virtual device state correct and provide the correct virtualization of a device.

Bulk and Interrupt

The bulk and interrupt transfer types are relativly simple compared to the control transfer. VUSB is not inspecting the request content or anything, but passes it down the device.

Bulk and Interrupt

This kind of transfers hasn't yet been implemented.

Generated by  Doxygen 1.6.0   Back to index