1.. _ivshmem_driver:
2
3Inter-VM Shared Memory
4######################
5
6.. contents::
7   :local:
8   :depth: 2
9
10Overview
11********
12
13As Zephyr is enabled to run as a guest OS on Qemu and
14`ACRN <https://projectacrn.github.io/latest/tutorials/using_zephyr_as_uos.html>`_
15it might be necessary to make VMs aware of each other, or aware of the host.
16This is made possible by exposing a shared memory among parties via a feature
17called ivshmem, which stands for inter-VM Shared Memory.
18
19The two types are supported: a plain shared memory (ivshmem-plain) or a shared
20memory with the ability for a VM to generate an interruption on another, and
21thus to be interrupted as well itself (ivshmem-doorbell).
22
23Please refer to the official `Qemu ivshmem documentation
24<https://www.qemu.org/docs/master/system/devices/ivshmem.html>`_ for more information.
25
26Support
27*******
28
29Zephyr supports both versions: plain and doorbell. Ivshmem driver can be built
30by enabling :kconfig:option:`CONFIG_IVSHMEM`. By default, this will expose the plain
31version. :kconfig:option:`CONFIG_IVSHMEM_DOORBELL` needs to be enabled to get the
32doorbell version.
33
34Because the doorbell version uses MSI-X vectors to support notification vectors,
35the :kconfig:option:`CONFIG_IVSHMEM_MSI_X_VECTORS` has to be tweaked to the number of
36vectors that will be needed.
37
38Note that a tiny shell module can be exposed to test the ivshmem feature by
39enabling :kconfig:option:`CONFIG_IVSHMEM_SHELL`.
40
41ivshmem-v2
42**********
43
44Zephyr also supports ivshmem-v2:
45
46https://github.com/siemens/jailhouse/blob/master/Documentation/ivshmem-v2-specification.md
47
48This is primarily used for IPC in the Jailhouse hypervisor
49(e.g. :zephyr:code-sample:`eth-ivshmem`). It is also possible to use ivshmem-v2 without
50Jailhouse by building the Siemens fork of QEMU, and modifying the QEMU launch flags:
51
52https://github.com/siemens/qemu/tree/wip/ivshmem2
53
54API Reference
55*************
56
57.. doxygengroup:: ivshmem
58