1.. _enable_ivshmem:
2
3Enable Inter-VM Shared Memory Communication (IVSHMEM)
4#####################################################
5
6About Inter-VM Shared Memory Communication (IVSHMEM)
7****************************************************
8
9Inter-VM shared memory communication allows VMs to communicate with each other
10via a shared memory mechanism.
11
12As an example, users in the industrial segment can use a shared memory region to
13exchange commands and responses between a Windows VM that is taking inputs from
14operators and a real-time VM that is running real-time tasks.
15
16The ACRN Device Model or hypervisor emulates a virtual PCI device (called an
17IVSHMEM device) to expose this shared memory's base address and size.
18
19* Device Model: The IVSHMEM device is emulated in the ACRN Device Model, and the
20  shared memory regions are reserved in the Service VM's memory space. This
21  solution only supports communication between post-launched User VMs.
22
23* Hypervisor: The IVSHMEM device is emulated in the hypervisor, and the shared
24  memory regions are reserved in the hypervisor's memory space. This solution
25  works for both pre-launched and post-launched User VMs.
26
27While both solutions can be used in the same ACRN configuration, VMs using
28different solutions cannot communicate with each other.
29
30Dependencies and Constraints
31****************************
32
33Consider the following dependencies and constraints:
34
35* Inter-VM shared memory communication is a hardware-neutral feature.
36
37* Guest OSes are required to have either of the following:
38
39  - An IVSHMEM driver, such as `virtio-WIN
40    <https://github.com/virtio-win/kvm-guest-drivers-windows>`__ for Windows and
41    `ivshmem APIs
42    <https://docs.zephyrproject.org/apidoc/latest/group__ivshmem.html>`__ in
43    Zephyr
44
45  - A mechanism granting user-space applications access to a PCI device, such as
46    the `Userspace I/O (UIO) driver
47    <https://www.kernel.org/doc/html/latest/driver-api/uio-howto.html>`__ in
48    Linux
49
50Configuration Overview
51**********************
52
53The :ref:`acrn_configurator_tool` lets you configure inter-VM shared memory
54communication among VMs. The following documentation is a general overview of
55the configuration process.
56
57To configure inter-VM shared memory communication among VMs, go to the
58**Hypervisor Global Settings > Basic Parameters > InterVM shared memory**. Click
59**+** to add the first shared memory region.
60
61.. image:: images/configurator-ivshmem01.png
62   :align: center
63   :class: drop-shadow
64
65For the shared memory region:
66
67#. Enter a name for the shared memory region.
68#. Select the source of the emulation, either Hypervisor or Device Model.
69#. Select the size of the shared memory region.
70#. **Enter shared memory region ID, which can be in hexadecimal or decimal format**.
71    .. note::
72       Default value is 0 and IDs in 0x001 ~ 0xFFF  are reserved, 0x1000 ~ 0xFFFF are available.
73#. Select at least two VMs that can use the shared memory region.
74#. Enter a virtual Board:Device.Function (BDF) address for each VM or leave it
75   blank. If the field is blank, the tool provides an address when the
76   configuration is saved.
77
78#. Add more VMs to the shared memory region by clicking **+** on the right
79   side of an existing VM. Or click **-** to delete a VM.
80
81To add another shared memory region, click **+** on the right side of an
82existing region. Or click **-** to delete a region.
83
84.. image:: images/configurator-ivshmem02.png
85   :align: center
86   :class: drop-shadow
87
88Learn More
89**********
90
91ACRN supports multiple inter-VM communication methods. For a comparison, see
92:ref:`inter-vm_communication`.
93
94For details on ACRN IVSHMEM high-level design, see :ref:`ivshmem-hld`.
95