doc: add inter-vm communication example
Add the example for two post-launched VMs communication
@@ -111,3 +111,58 @@ where
- ``shm_size`` - Specify a shared memory size. The two communicating
VMs must define the same size.
+
+
+Inter-VM Communication Example
+******************************
+
+Using inter-vm communication between two linux-based post-launched VMs (VM1 and
+VM2) as an example.
+
+Firstly, we need to add a new virtual PCI device for both of VMs, the device type
+is ``ivshmem``, shared memory name is test and shared memory size is 4096 bytes.
+
+.. note:: both VMs should have same shared memory name and size
+
+- VM1 Launch Script Sample::
+
+ 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/clear/uos/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::
+
+ acrn-dm -A -m $mem_size -s 0:0,hostbridge
+ -s 2,pci-gvt -G "$2"
+ -s 3,virtio-blk,/home/clear/uos/uos2.img
+ -s 4,virtio-net,tap0
+ ``-s 5,ivshmem,test,4096``
+ --ovmf /usr/share/acrn/bios/OVMF.fd
+ $vm_name
+
+Secondly, boot two VMs and use ``lspci`` to check the virtual device is ready for each VM.
+
+- For VM1, it is ``00:06.0 RAM memory: Red Hat, Inc. Inter-VM shared memory (rev 01)``
+- For VM2, it is ``00:05.0 RAM memory: Red Hat, Inc. Inter-VM shared memory (rev 01)``
+
+Thirdly, using below 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
+
+Finally, user application can get shared memory base address from ``ivshmem`` device
+BAR resource (``/sys/class/uio/uioX/device/resource2``) and shared memory size from
+``ivshmem`` device config resource (``/sys/class/uio/uioX/device/config``).
+
+.. note:: the X in uioX is a number that can be retrieved using the ``ls`` command.
+ VM1 can use ``ls -lh /sys/bus/pci/devices/0000\:00\:06.0/uio`` and VM2 can use
+ ``ls -lh /sys/bus/pci/devices/0000\:00\:05.0/uio``.
