Inter-VM Shared Memory¶
Overview¶
As Zephyr is enabled to run as a guest OS on Qemu and ACRN it might be necessary to make VMs aware of each other, or aware of the host. This is made possible by exposing a shared memory among parties via a feature called ivshmem, which stands for inter-VM Shared Memory.
The Two types are supported: a plain shared memory (ivshmem-plain) or a shared memory with the ability for a VM to generate an interruption on another, and thus to be interrupted as well itself (ivshmem-doorbell).
Please refer to the official Qemu ivshmem documentation for more information.
Support¶
Zephyr supports both version: plain and doorbell. Ivshmem driver can be build by enabling :kconfig:`CONFIG_IVSHMEM`. By default, this will expose the plain version. :kconfig:`CONFIG_IVSHMEM_DOORBELL` needs to be enabled to get the doorbell version.
Because the doorbell version uses MSI-X vectors to support notification vectors, the :kconfig:`CONFIG_IVSHMEM_MSI_X_VECTORS` has to be tweaked to the amount of vectors that will be needed.
Note that a tiny shell module can be exposed to test the ivshmem feature by enabling :kconfig:`CONFIG_IVSHMEM_SHELL`.
API Reference¶
-
group
ivshmem ivshmem reference API
Typedefs
-
typedef int (*
ivshmem_register_handler_f)(const struct device *dev, struct k_poll_signal *signal, uint16_t vector)¶
Functions
-
size_t
ivshmem_get_mem(const struct device *dev, uintptr_t *memmap)¶ Get the inter-VM shared memory.
- Parameters
dev – Pointer to the device structure for the driver instance
memmap – A pointer to fill in with the memory address
- Returns
the size of the memory mapped, or 0
-
uint32_t
ivshmem_get_id(const struct device *dev)¶ Get our VM ID.
- Parameters
dev – Pointer to the device structure for the driver instance
- Returns
our VM ID or 0 if we are not running on doorbell version
-
uint16_t
ivshmem_get_vectors(const struct device *dev)¶ Get the number of interrupt vectors we can use.
- Parameters
dev – Pointer to the device structure for the driver instance
- Returns
the number of available interrupt vectors
-
int
ivshmem_int_peer(const struct device *dev, uint32_t peer_id, uint16_t vector)¶ Interrupt another VM.
- Parameters
dev – Pointer to the device structure for the driver instance
peer_id – The VM ID to interrupt
vector – The interrupt vector to use
- Returns
0 on success, a negative errno otherwise
-
int
ivshmem_register_handler(const struct device *dev, struct k_poll_signal *signal, uint16_t vector)¶ Register a vector notification (interrupt) handler.
Note: The returned status, if positive, to a raised signal is the vector that generated the signal. This lets the possibility to the user to have one signal for all vectors, or one per-vector.
- Parameters
dev – Pointer to the device structure for the driver instance
signal – A pointer to a valid and ready to be signaled struct k_poll_signal. Or NULL to unregister any handler registered for the given vector.
vector – The interrupt vector to get notification from
- Returns
0 on success, a negative errno otherwise
-
struct
ivshmem_driver_api¶ - #include <ivshmem.h>
-
typedef int (*