doc: update release_2.2 branch documentation

Update documentaiton in the release_2.2 branch with changes made after
tagged for code freeze

Signed-off-by: David B. Kinder <[email protected]>

Author: dbkinder

doc/develop.rst

@@ -33,6 +33,7 @@ Service VM Tutorials
    :maxdepth: 1
 
    tutorials/running_deb_as_serv_vm
+   tutorials/using_yp
 
 User VM Tutorials
 *****************
@@ -72,6 +73,7 @@ Enable ACRN Features
    tutorials/acrn_on_qemu
    tutorials/using_grub
    tutorials/pre-launched-rt
+   tutorials/enable_ivshmem
 
 Debug
 *****

doc/developer-guides/hld/hld-emulated-devices.rst

@@ -22,4 +22,4 @@ documented in this section.
    Hostbridge emulation <hostbridge-virt-hld>
    AT keyboard controller emulation <atkbdc-virt-hld>
    Split Device Model <split-dm>
-   Shared memory based inter-vm communication <ivshmem-hld>
+   Shared memory based inter-VM communication <ivshmem-hld>

doc/developer-guides/hld/hld-overview.rst

@@ -5,7 +5,7 @@ ACRN high-level design overview
 
 ACRN is an open source reference hypervisor (HV) that runs on top of Intel
 platforms (APL, KBL, etc) for heterogeneous scenarios such as the Software Defined
-Cockpit (SDC), or the In-Vehicle Experience (IVE) for automotive, or HMI & Real-Time OS for industry. ACRN provides embedded hypervisor vendors with a reference
+Cockpit (SDC), or the In-Vehicle Experience (IVE) for automotive, or HMI & real-time OS for industry. ACRN provides embedded hypervisor vendors with a reference
 I/O mediation solution with a permissive license and provides auto makers and
 industry users a reference software stack for corresponding use.
 
@@ -124,7 +124,7 @@ ACRN 2.0
 ========
 
 ACRN 2.0 is extending ACRN to support pre-launched VM (mainly for safety VM)
-and Real-Time (RT) VM.
+and real-time (RT) VM.
 
 :numref:`overview-arch2.0` shows the architecture of ACRN 2.0; the main difference
 compared to ACRN 1.0 is that:

doc/developer-guides/hld/hld-security.rst

@@ -1016,7 +1016,7 @@ access is like this:
 #. If the verification is successful in eMMC RPMB controller, then the
    data will be written into storage device.
 
-This work flow of authenticated data read is very similar to this flow
+This workflow of authenticated data read is very similar to this flow
 above, but in reverse order.
 
 Note that there are some security considerations in this design:

doc/developer-guides/hld/hld-virtio-devices.rst

@@ -358,7 +358,7 @@ general workflow of ioeventfd.
    :align: center
    :name: ioeventfd-workflow
 
-   ioeventfd general work flow
+   ioeventfd general workflow
 
 The workflow can be summarized as:
 

doc/developer-guides/hld/hv-ioc-virt.rst

@@ -13,7 +13,7 @@ SoC and back, as well as signals the SoC uses to control onboard
 peripherals.
 
 .. note::
-   NUC and UP2 platforms do not support IOC hardware, and as such, IOC
+   Intel NUC and UP2 platforms do not support IOC hardware, and as such, IOC
    virtualization is not supported on these platforms.
 
 The main purpose of IOC virtualization is to transfer data between
@@ -131,7 +131,7 @@ There are five parts in this high-level design:
 * State transfer introduces IOC mediator work states
 * CBC protocol illustrates the CBC data packing/unpacking
 * Power management involves boot/resume/suspend/shutdown flows
-* Emulated CBC commands introduces some commands work flow
+* Emulated CBC commands introduces some commands workflow
 
 IOC mediator has three threads to transfer data between User VM and Service VM. The
 core thread is responsible for data reception, and Tx and Rx threads are

doc/developer-guides/hld/hv-partitionmode.rst

@@ -57,8 +57,8 @@ configuration and copies them to the corresponding guest memory.
 .. figure:: images/partition-image18.png
    :align: center
 
-ACRN set-up for guests
-**********************
+ACRN setup for guests
+*********************
 
 Cores
 =====

doc/developer-guides/hld/hv-rdt.rst

@@ -39,7 +39,7 @@ resource allocator.) The user can check the cache capabilities such as cache
 mask and max supported CLOS as described in :ref:`rdt_detection_capabilities`
 and then program the IA32_type_MASK_n and IA32_PQR_ASSOC MSR with a
 CLOS ID, to select a cache mask to take effect. These configurations can be 
-done in scenario xml file under ``FEATURES`` section as shown in the below example.
+done in scenario XML file under ``FEATURES`` section as shown in the below example.
 ACRN uses VMCS MSR loads on every VM Entry/VM Exit for non-root and root modes
 to enforce the settings.
 
@@ -52,7 +52,7 @@ to enforce the settings.
             <CLOS_MASK desc="Cache Capacity Bitmask">0xF</CLOS_MASK>
 
 Once the cache mask is set of each individual CPU, the respective CLOS ID
-needs to be set in the scenario xml file under ``VM`` section. If user desires
+needs to be set in the scenario XML file under ``VM`` section. If user desires
 to use CDP feature, CDP_ENABLED should be set to ``y``.
 
    .. code-block:: none
@@ -106,7 +106,7 @@ that corresponds to each CLOS and then setting IA32_PQR_ASSOC MSR with CLOS
 users can check the MBA capabilities such as mba delay values and
 max supported CLOS as described in :ref:`rdt_detection_capabilities` and
 then program the IA32_MBA_MASK_n and IA32_PQR_ASSOC MSR with the CLOS ID.
-These configurations can be done in scenario xml file under ``FEATURES`` section
+These configurations can be done in scenario XML file under ``FEATURES`` section
 as shown in the below example. ACRN uses VMCS MSR loads on every VM Entry/VM Exit
 for non-root and root modes to enforce the settings.
 
@@ -120,7 +120,7 @@ for non-root and root modes to enforce the settings.
             <MBA_DELAY desc="Memory Bandwidth Allocation delay value">0</MBA_DELAY>
 
 Once the cache mask is set of each individual CPU, the respective CLOS ID
-needs to be set in the scenario xml file under ``VM`` section.
+needs to be set in the scenario XML file under ``VM`` section.
 
    .. code-block:: none
       :emphasize-lines: 2

doc/developer-guides/hld/ivshmem-hld.rst

@@ -15,17 +15,24 @@ Inter-VM Communication Overview
    :align: center
    :name: ivshmem-architecture-overview
 
-   ACRN shared memory based inter-vm communication architecture
+   ACRN shared memory based inter-VM communication architecture
 
-The ``ivshmem`` device is emulated in the ACRN device model (dm-land)
-and its shared memory region is allocated from the Service VM's memory
-space. This solution only supports communication between post-launched
-VMs.
+There are two ways ACRN can emulate the ``ivshmem`` device:
 
-.. note:: In a future implementation, the ``ivshmem`` device could
-   instead be emulated in the hypervisor (hypervisor-land) and the shared
-   memory regions reserved in the hypervisor's memory space. This solution
-   would work for both pre-launched and post-launched VMs.
+``ivshmem`` dm-land
+   The ``ivshmem`` device is emulated in the ACRN device model,
+   and the shared memory regions are reserved in the Service VM's
+   memory space.  This solution only supports communication between
+   post-launched VMs.
+
+``ivshmem`` hv-land
+   The ``ivshmem`` device is emulated in the hypervisor, and the
+   shared memory regions are reserved in the hypervisor's
+   memory space.  This solution works for both pre-launched and
+   post-launched VMs.
+
+While both solutions can be used at the same time,  Inter-VM communication
+may only be done between VMs using the same solution.
 
 ivshmem hv:
    The **ivshmem hv** implements register virtualization
@@ -98,89 +105,7 @@ MMIO Registers Definition
 Usage
 *****
 
-To support two post-launched VMs communicating via an ``ivshmem`` device,
-add this line as an ``acrn-dm`` boot parameter::
-
-  -s slot,ivshmem,shm_name,shm_size
-
-where
-
--  ``-s slot`` - Specify the virtual PCI slot number
-
--  ``ivshmem`` - Virtual PCI device name
-
--  ``shm_name`` - Specify a shared memory name. Post-launched VMs with the
-   same ``shm_name`` share a shared memory region.
-
--  ``shm_size`` - Specify a shared memory size. The two communicating
-   VMs must define the same size.
-
-.. note:: This device can be used with Real-Time VM (RTVM) as well.
-
-Inter-VM Communication Example
-******************************
-
-The following example uses inter-vm communication between two Linux-based
-post-launched VMs (VM1 and VM2).
-
-.. note:: An ``ivshmem`` Windows driver exists and can be found `here <https://github.com/virtio-win/kvm-guest-drivers-windows/tree/master/ivshmem>`_
-
-1. Add a new virtual PCI device for both VMs: the device type is
-   ``ivshmem``, shared memory name is ``test``, and shared memory size is
-   4096 bytes. Both VMs must have the same shared memory name and size:
-
-   - VM1 Launch Script Sample
-
-     .. code-block:: none
-        :emphasize-lines: 7
-
-        acrn-dm -A -m $mem_size -s 0:0,hostbridge \
-         -s 2,pci-gvt -G "$2" \
-         -s 5,virtio-console,@stdio:stdio_port \
-         -s 6,virtio-hyper_dmabuf \
-         -s 3,virtio-blk,/home/acrn/uos1.img \
-         -s 4,virtio-net,tap0 \
-         -s 6,ivshmem,test,4096 \
-         -s 7,virtio-rnd \
-         --ovmf /usr/share/acrn/bios/OVMF.fd \
-         $vm_name
-
-
-   - VM2 Launch Script Sample
-
-     .. code-block:: none
-        :emphasize-lines: 5
-
-        acrn-dm -A -m $mem_size -s 0:0,hostbridge \
-         -s 2,pci-gvt -G "$2" \
-         -s 3,virtio-blk,/home/acrn/uos2.img \
-         -s 4,virtio-net,tap0 \
-         -s 5,ivshmem,test,4096 \
-         --ovmf /usr/share/acrn/bios/OVMF.fd \
-         $vm_name
-
-2. Boot two VMs and use ``lspci | grep "shared memory"`` to verify that the virtual device is ready for each VM.
-
-   -  For VM1, it shows ``00:06.0 RAM memory: Red Hat, Inc. Inter-VM shared memory (rev 01)``
-   -  For VM2, it shows ``00:05.0 RAM memory: Red Hat, Inc. Inter-VM shared memory (rev 01)``
-
-3. Use these commands to probe the device::
-
-     $ sudo modprobe uio
-     $ sudo modprobe uio_pci_generic
-     $ sudo echo "1af4 1110" > /sys/bus/pci/drivers/uio_pci_generic/new_id
-
-4. Finally, a user application can get the shared memory base address from
-   the ``ivshmem`` device BAR resource
-   (``/sys/class/uio/uioX/device/resource2``) and the shared memory size from
-   the ``ivshmem`` device config resource
-   (``/sys/class/uio/uioX/device/config``).
-
-   The ``X`` in ``uioX`` above, is a number that can be retrieved using the
-   ``ls`` command:
-
-   - For VM1 use ``ls -lh /sys/bus/pci/devices/0000:00:06.0/uio``
-   - For VM2 use ``ls -lh /sys/bus/pci/devices/0000:00:05.0/uio``
+For usage information, see :ref:`enable_ivshmem`
 
 Inter-VM Communication Security hardening (BKMs)
 ************************************************

doc/developer-guides/hld/system-timer-hld.rst

@@ -86,7 +86,7 @@ I/O ports definition::
 RTC emulation
 =============
 
-ACRN supports RTC (Real-Time Clock) that can only be accessed through
+ACRN supports RTC (real-time clock) that can only be accessed through
 I/O ports (0x70 and 0x71).
 
 0x70 is used to access CMOS address register and 0x71 is used to access