1.. _usb_virtualization:
2
3USB Virtualization
4##################
5
6Universal Serial Bus (USB) is an industry standard that
7establishes specifications for cables, connectors, and protocols for
8connection, communication, and power supply between personal computers
9and their peripheral devices.
10
11.. figure:: images/usb-image51.png
12   :align: center
13   :name: usb-virt-arch
14
15   USB Architecture Overview
16
17
18The ACRN USB virtualization includes
19emulation of three components, described here and shown in
20:numref:`usb-virt-arch`:
21
22- **xHCI DM** (Host Controller Interface) provides multiple
23  instances of virtual xHCI controllers to share among multiple User
24  VMs, each USB port can be assigned and dedicated to a VM by user
25  settings.
26
27- **xDCI controller** (Device Controller Interface)
28  can be passed through to the
29  specific User VM with I/O MMU assistance.
30
31- **DRD DM** (Dual Role Device) emulates the PHY MUX control
32  logic. The sysfs interface in a User VM is used to trap the switch operation
33  into DM, and the sysfs interface in the Service VM is used to operate on the
34  physical registers to switch between DCI and HCI role.
35
36  On Apollo Lake platforms, the sysfs interface path is
37  ``/sys/class/usb_role/intel_xhci_usb_sw/role``. If the user echos the string
38  ``device`` to the role node, the USB PHY will be connected with the xDCI
39  controller as
40  device mode. Similarly, by echoing ``host``, the USB PHY will be
41  connected with the xHCI controller as host mode.
42
43An xHCI register access from a User VM will induce an EPT trap from the User VM
44to
45DM, and the xHCI DM or DRD DM will emulate hardware behaviors to make
46the subsystem run.
47
48USB Host Virtualization
49***********************
50
51USB host virtualization is implemented as shown in
52:numref:`xhci-dm-arch`:
53
54.. figure:: images/usb-image10.png
55   :align: center
56   :name: xhci-dm-arch
57
58   xHCI DM Software Architecture
59
60The following components make up the ACRN USB stack supporting xHCI
61DM:
62
63- **xHCI DM** emulates the xHCI controller logic following the xHCI spec.
64
65- **USB core** is a middle abstract layer to isolate the USB controller
66  emulators and USB device emulators.
67
68- **USB Port Mapper** maps the specific native physical USB
69  ports to virtual USB ports. It communicates with
70  native USB ports though libusb.
71
72All the USB data buffers from a User VM are in the form of TRB
73(Transfer Request Blocks), according to xHCI spec. xHCI DM will fetch
74these data buffers when the related xHCI doorbell registers are set.
75The data will convert to ``struct usb_data_xfer`` and, through USB core,
76forward to the USB port mapper module which will communicate with the native USB
77stack over libusb.
78
79The Device Model configuration command syntax for xHCI is as follows::
80
81   -s <slot>,xhci,[bus1-port1,bus2-port2]
82
83- *slot*: virtual PCI slot number in DM
84- *bus-port*: specify which physical USB ports need to map to a User VM.
85
86A simple example::
87
88   -s 7,xhci,1-2,2-2
89
90This configuration means the virtual xHCI will appear in PCI slot 7
91in the User VM, and any physical USB device attached on 1-2 or 2-2 will be
92detected by a User VM and used as expected.
93
94USB DRD Virtualization
95**********************
96
97USB DRD (Dual Role Device) emulation works as shown in this figure:
98
99.. figure:: images/usb-image31.png
100   :align: center
101
102   xHCI DRD DM Software Architecture
103
104ACRN emulates the DRD hardware logic of an Apollo Lake platform to
105support the dual role requirement. The DRD feature is implemented as an xHCI
106vendor extended capability.  ACRN emulates
107the same way, so the native driver can be reused in a User VM. When a User VM DRD
108driver reads or writes the related xHCI extended registers, these accesses will
109be captured by xHCI DM. xHCI DM uses the native DRD related
110sysfs interface to do the Host/Device mode switch operations.
111
112The Device Model configuration command syntax for xHCI DRD is as
113follows::
114
115   -s <slot>,xhci,[bus1-port1,bus2-port2],cap=platform
116
117- *cap*: cap means virtual xHCI capability. This parameter
118  indicates virtual xHCI should emulate the named platform's xHCI
119  capabilities.
120
121A simple example::
122
123   -s 7,xhci,1-2,2-2,cap=apl
124
125This configuration means the virtual xHCI should emulate xHCI
126capabilities for the Apollo Lake platform, which supports the DRD
127feature.
128
129Interface Specification
130***********************
131
132.. note:: Reference the Doxygen-generated API content.
133