131 lines
4.2 KiB
ReStructuredText
131 lines
4.2 KiB
ReStructuredText
.. _usb_virtualization:
|
||
|
||
USB Virtualization
|
||
##################
|
||
|
||
Universal Serial Bus (USB) is an industry standard that
|
||
establishes specifications for cables, connectors, and protocols for
|
||
connection, communication, and power supply between personal computers
|
||
and their peripheral devices.
|
||
|
||
.. figure:: images/usb-image51.png
|
||
:align: center
|
||
:name: usb-virt-arch
|
||
|
||
USB architecture overview
|
||
|
||
|
||
The ACRN USB virtualization includes
|
||
emulation of three components, described here and shown in
|
||
:numref:`usb-virt-arch`:
|
||
|
||
- **xHCI DM** (Host Controller Interface) provides multiple
|
||
instances of virtual xHCI controllers to share among multiple User
|
||
OSes, each USB port can be assigned and dedicated to a VM by user
|
||
settings.
|
||
|
||
- **xDCI controller** (Device Controller Interface)
|
||
can be passed through to the
|
||
specific User OS with I/O MMU assistance.
|
||
|
||
- **DRD DM** (Dual Role Device) emulates the PHY MUX control
|
||
logic. The sysfs interface in UOS is used to trap the switch operation
|
||
into DM, and the the sysfs interface in SOS is used to operate on the physical
|
||
registers to switch between DCI and HCI role.
|
||
|
||
On Intel Apollo Lake platform, the sysfs interface path is
|
||
``/sys/class/usb_role/intel_xhci_usb_sw/role``. If user echos string
|
||
``device`` to role node, the usb phy will be connected with xDCI controller as
|
||
device mode. Similarly, by echoing ``host``, the usb phy will be
|
||
connected with xHCI controller as host mode.
|
||
|
||
An xHCI register access from UOS will induce EPT trap from UOS to
|
||
DM, and the xHCI DM or DRD DM will emulate hardware behaviors to make
|
||
the subsystem run.
|
||
|
||
USB host virtualization
|
||
***********************
|
||
|
||
USB host virtualization is implemented as shown in
|
||
:numref:`xhci-dm-arch`:
|
||
|
||
.. figure:: images/usb-image10.png
|
||
:align: center
|
||
:name: xhci-dm-arch
|
||
|
||
xHCI DM software architecture
|
||
|
||
The yellow-colored components make up the ACRN USB stack supporting xHCI
|
||
DM:
|
||
|
||
- **xHCI DM** emulates the xHCI controller logic following the xHCI spec;
|
||
|
||
- **USB core** is a middle abstract layer to isolate the USB controller
|
||
emulators and USB device emulators.
|
||
|
||
- **USB Port Mapper** maps the specific native physical USB
|
||
ports to virtual USB ports. It communicate with
|
||
native USB ports though libusb.
|
||
|
||
All the USB data buffers from UOS (User OS) are in the form of TRB
|
||
(Transfer Request Blocks), according to xHCI spec. xHCI DM will fetch
|
||
these data buffers when the related xHCI doorbell registers are set.
|
||
These data will convert to *struct usb_data_xfer* and, through USB core,
|
||
forward to the USB port mapper module which will communicate with native USB
|
||
stack over libusb.
|
||
|
||
The device model configuration command syntax for xHCI is as follows::
|
||
|
||
-s <slot>,xhci,[bus1-port1,bus2-port2]
|
||
|
||
- *slot*: virtual PCI slot number in DM
|
||
- *bus-port*: specify which physical USB ports need to map to UOS.
|
||
|
||
A simple example::
|
||
|
||
-s 7,xhci,1-2,2-2
|
||
|
||
This configuration means the virtual xHCI will appear in PCI slot 7
|
||
in UOS, and any physical USB device attached on 1-2 or 2-2 will be
|
||
detected by UOS and used as expected.
|
||
|
||
USB DRD virtualization
|
||
**********************
|
||
|
||
USB DRD (Dual Role Device) emulation works as shown in this figure:
|
||
|
||
.. figure:: images/usb-image31.png
|
||
:align: center
|
||
|
||
xHCI DRD DM software architecture
|
||
|
||
ACRN emulates the DRD hardware logic of an Intel Apollo Lake platform to
|
||
support the dual role requirement. The DRD feature is implemented as xHCI
|
||
vendor extended capability. ACRN emulates
|
||
the same way, so the native driver can be reused in UOS. When UOS DRD
|
||
driver reads or writes the related xHCI extended registers, these access will
|
||
be captured by xHCI DM. xHCI DM uses the native DRD related
|
||
sysfs interface to do the Host/Device mode switch operations.
|
||
|
||
The device model configuration command syntax for xHCI DRD is as
|
||
follows::
|
||
|
||
-s <slot>,xhci,[bus1-port1,bus2-port2],cap=platform
|
||
|
||
- *cap*: cap means virtual xHCI capability. This parameter
|
||
indicates virtual xHCI should emulate the named platform’s xHCI
|
||
capabilities.
|
||
|
||
A simple example::
|
||
|
||
-s 7,xhci,1-2,2-2,cap=apl
|
||
|
||
This configuration means the virtual xHCI should emulate xHCI
|
||
capabilities for the Intel Apollo Lake platform, which supports DRD
|
||
feature.
|
||
|
||
Interface Specification
|
||
***********************
|
||
|
||
.. note:: reference doxygen-generated API content
|