doc: doc: update HLD Emulated Devices

Transcode, edit, and upload HLD 0.7 section 5 (Emulated Devices), including

- 5.1 USB Virtualization (merge with previously edited doc),
- 5.2 UART virtualization (merge with previous edited doc),
- NOT INCLUDING 5.3 (Automotive) I/O controller virtualization
- 5.4 Watchdog virtualization (merge with previously edited doc)
- 5.5 GVT-g GPU Virtualization (merge previously edited doc)

Tracked-on: #1687

Signed-off-by: David B. Kinder <david.b.kinder@intel.com>

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 <hld-APL_GVT-g>
+   usb-virt-hld
    UART virtualization <uart-virt-hld>
    Watchdoc virtualization <watchdog-hld>
+   random-virt-hld
+   GVT-g GPU Virtualization <hld-APL_GVT-g>

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 <slot_number>,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.

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 <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

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
+Make sure the UOS kernel has the I6300ESB driver enabled:
-boots up, the watchdog device will be created as node ``/dev/watchdog``,
+``CONFIG_I6300ESB_WDT=y``. After the UOS boots up, the watchdog device
-and can be used as a normal device file.
+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