doc: add ivhshmem hv-land introduction

Ivshmem hv-land solution emulates the ivshmem device in hypervisor
and the shared memory is reserved in the hypervisor's memory space.
And it can provide inter-vm communication for both pre-launched and
post-launched VMs.

This patch introduces the ivshmem hv-land solution including what
ivshmem hv-land is and how to use it.

Signed-off-by: Yuan Liu <yuan1.liu@intel.com>

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

@@ -17,15 +17,22 @@ Inter-VM Communication Overview
 
    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)
 ************************************************