diff --git a/doc/developer-guides/hld/hld-emulated-devices.rst b/doc/developer-guides/hld/hld-emulated-devices.rst index 482c56354..9723cc7a8 100644 --- a/doc/developer-guides/hld/hld-emulated-devices.rst +++ b/doc/developer-guides/hld/hld-emulated-devices.rst @@ -3,9 +3,16 @@ Emulated devices high-level design ################################## +Full virtualization device models can typically +reuse existing native device drivers to avoid implementing front-end +drivers. ACRN implements several fully virtualized devices, as +documented in this section. + .. toctree:: :maxdepth: 1 - GVT-g GPU Virtualization + usb-virt-hld UART virtualization Watchdoc virtualization + random-virt-hld + GVT-g GPU Virtualization diff --git a/doc/developer-guides/hld/images/ioc-image49.png b/doc/developer-guides/hld/images/ioc-image49.png new file mode 100644 index 000000000..3671654de Binary files /dev/null and b/doc/developer-guides/hld/images/ioc-image49.png differ diff --git a/doc/developer-guides/hld/images/ioc-image65.png b/doc/developer-guides/hld/images/ioc-image65.png new file mode 100644 index 000000000..52a80e30c Binary files /dev/null and b/doc/developer-guides/hld/images/ioc-image65.png differ diff --git a/doc/developer-guides/hld/images/rand-virt.png b/doc/developer-guides/hld/images/rand-virt.png new file mode 100644 index 000000000..0eb24bff1 Binary files /dev/null and b/doc/developer-guides/hld/images/rand-virt.png differ diff --git a/doc/developer-guides/hld/images/usb-image10.png b/doc/developer-guides/hld/images/usb-image10.png new file mode 100644 index 000000000..dd7ecf447 Binary files /dev/null and b/doc/developer-guides/hld/images/usb-image10.png differ diff --git a/doc/developer-guides/hld/images/usb-image31.png b/doc/developer-guides/hld/images/usb-image31.png new file mode 100644 index 000000000..f712f4435 Binary files /dev/null and b/doc/developer-guides/hld/images/usb-image31.png differ diff --git a/doc/developer-guides/hld/images/usb-image51.png b/doc/developer-guides/hld/images/usb-image51.png new file mode 100644 index 000000000..1cbdb5204 Binary files /dev/null and b/doc/developer-guides/hld/images/usb-image51.png differ diff --git a/doc/developer-guides/hld/random-virt-hld.rst b/doc/developer-guides/hld/random-virt-hld.rst new file mode 100644 index 000000000..3e0036b15 --- /dev/null +++ b/doc/developer-guides/hld/random-virt-hld.rst @@ -0,0 +1,76 @@ +.. _random_virtualization: + +Random device virtualization +############################ + +The virtual random device virtio-rnd provides a virtual hardware random +source for UOS, based on virtio user mode framework. It simulates a PCI +device based on virtio specification. + +Architecture +************ + +:numref:`rand-virt-arch` shows the Random Device Virtualization Architecture in ACRN. +The green components are parts of the ACRN solution while the dark +components are parts of Linux software or third party tools. + +virtio-rnd is implemented as a virtio legacy device in the ACRN device +model (DM), and is registered as a PCI virtio device to the guest OS +(UOS). Tools such as :command:`od` (dump a file in octal or other format) can +be used to read random values from ``/dev/random``. This device file in +UOS is bound with the frontend virtio-rng driver. (The guest kernel must +be built with ``CONFIG_HW_RANDOM_VIRTIO=y``). The backend +virtio-rnd reads the HW random value from ``/dev/random`` in SOS and sends +them to frontend. + +.. figure:: images/rand-virt.png + :align: center + :name: rand-virt-arch + + Random Device Virtualization in ACRN + +How to Use +********** + +Add a pci slot to the device model acrn-dm command line, for example:: + + -s ,virtio-rnd + +Check if the frontend virtio_rng driver is available in UOS: + +.. code-block:: console + + # cat /sys/class/misc/hw_random/rng_available + virtio_rng.0 + +Check if frontend virtio_rng is currently connected to ``/dev/random``: + +.. code-block:: console + + # cat /sys/class/misc/hw_random/rng_current + virtio_rng.0 + +Read random values: + +.. code-block:: console + + # od /dev/random + 0000000 007265 175751 147323 164223 060601 057377 027072 106352 + 0000020 040765 045645 155773 111724 037572 152033 036001 056073 + 0000040 057164 065021 024005 031500 156630 026635 022440 000127 + 0000060 115071 046756 071656 106721 161340 106726 175275 072403 + 0000100 011265 000420 061137 103723 001107 006430 061151 132766 + 0000120 166216 015074 100505 015473 057324 102727 005126 051731 + 0000140 003727 071115 167622 071407 120301 002616 047451 120733 + 0000160 174117 133164 161231 035076 013700 164114 031627 001202 + 0000200 011467 055650 016365 140074 060277 150601 043610 006403 + 0000220 016170 071666 065540 026615 055073 162363 012002 112371 + 0000240 000767 157121 125007 141671 000327 173741 056415 155463 + 0000260 105504 066453 152754 136314 175213 063541 001420 053025 + 0000300 047631 167425 044125 063176 171334 177234 050063 031640 + ... + + +.. note:: HW randomness is a precious resource of the system. The + :command:`od` command will block and wait until there is randomness + available. diff --git a/doc/developer-guides/hld/usb-virt-hld.rst b/doc/developer-guides/hld/usb-virt-hld.rst new file mode 100644 index 000000000..ed998dcd1 --- /dev/null +++ b/doc/developer-guides/hld/usb-virt-hld.rst @@ -0,0 +1,130 @@ +.. _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 ,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 ,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 diff --git a/doc/developer-guides/hld/watchdog-hld.rst b/doc/developer-guides/hld/watchdog-hld.rst index be03b6253..b462f5abd 100644 --- a/doc/developer-guides/hld/watchdog-hld.rst +++ b/doc/developer-guides/hld/watchdog-hld.rst @@ -88,9 +88,10 @@ timely kick action, it will call DM API to reboot that UOS. In the UOS launch script, add: ``-s xx,wdt-i6300esb`` into DM parameters. (xx is the virtual PCI BDF number as with other PCI devices) -Make sure the UOS kernel has the I6300ESB driver enabled: ``CONFIG_I6300ESB_WDT=y``. After the UOS -boots up, the watchdog device will be created as node ``/dev/watchdog``, -and can be used as a normal device file. +Make sure the UOS kernel has the I6300ESB driver enabled: +``CONFIG_I6300ESB_WDT=y``. After the UOS boots up, the watchdog device +will be created as node ``/dev/watchdog``, and can be used as a normal +device file. Usually the UOS needs a watchdog service (daemon) to run in userland and kick the watchdog periodically. If something prevents the daemon from