From e9cf9d032598dd942b8d4ae7be8cfa32327804c1 Mon Sep 17 00:00:00 2001
From: Tomasz Bursztyka <tomasz.bursztyka@linux.intel.com>
Date: Wed, 9 Dec 2020 12:46:38 +0100
Subject: [PATCH] doc: Adding ivshmem general and API documentation

A quick summary on what is ivshmem and its Zephyr driver API.

Signed-off-by: Tomasz Bursztyka <tomasz.bursztyka@linux.intel.com>
---
 doc/reference/index.rst                  |  1 +
 doc/reference/virtualization/index.rst   |  9 +++++
 doc/reference/virtualization/ivshmem.rst | 45 ++++++++++++++++++++++++
 include/drivers/virtualization/ivshmem.h | 10 ++++++
 4 files changed, 65 insertions(+)
 create mode 100644 doc/reference/virtualization/index.rst
 create mode 100644 doc/reference/virtualization/ivshmem.rst

diff --git a/doc/reference/index.rst b/doc/reference/index.rst
index dc42f63f142..29bb60fc973 100644
--- a/doc/reference/index.rst
+++ b/doc/reference/index.rst
@@ -34,3 +34,4 @@ API Reference
    util/index.rst
    settings/index.rst
    timing_functions/index.rst
+   virtualization/index.rst
diff --git a/doc/reference/virtualization/index.rst b/doc/reference/virtualization/index.rst
new file mode 100644
index 00000000000..4e80c660da8
--- /dev/null
+++ b/doc/reference/virtualization/index.rst
@@ -0,0 +1,9 @@
+.. _virtualization_reference:
+
+Virtualization
+##############
+
+.. toctree::
+   :maxdepth: 1
+
+   ivshmem.rst
diff --git a/doc/reference/virtualization/ivshmem.rst b/doc/reference/virtualization/ivshmem.rst
new file mode 100644
index 00000000000..9cb6314bc25
--- /dev/null
+++ b/doc/reference/virtualization/ivshmem.rst
@@ -0,0 +1,45 @@
+.. _ivshmem_driver:
+
+Inter-VM Shared Memory
+######################
+
+.. contents::
+   :local:
+   :depth: 2
+
+Overview
+********
+
+As Zephyr is enabled to run as a guest OS on Qemu and
+`ACRN <https://projectacrn.github.io/latest/tutorials/using_zephyr_as_uos.html>`_
+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
+<https://www.qemu.org/docs/master/system/ivshmem.html>`_ for more information.
+
+Support
+*******
+
+Zephyr supports both version: plain and doorbell. Ivshmem driver can be build
+by enabling :option:`CONFIG_IVSHMEM`. By default, this will expose the plain
+version. :option:`CONFIG_IVSHMEM_DOORBELL` needs no be enabled to get the
+doorbell version.
+
+Because the doorbell version uses MSI-X vectors to support notification vectors,
+the :option:`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 :option:`CONFIG_IVSHMEM_SHELL`.
+
+API Reference
+*************
+
+.. doxygengroup:: ivshmem
+   :project: Zephyr
diff --git a/include/drivers/virtualization/ivshmem.h b/include/drivers/virtualization/ivshmem.h
index 36299ec8433..252389c28d0 100644
--- a/include/drivers/virtualization/ivshmem.h
+++ b/include/drivers/virtualization/ivshmem.h
@@ -7,6 +7,12 @@
 #ifndef ZEPHYR_INCLUDE_DRIVERS_VIRTUALIZATION_IVSHMEM_H_
 #define ZEPHYR_INCLUDE_DRIVERS_VIRTUALIZATION_IVSHMEM_H_
 
+/**
+ * @brief ivshmem reference API
+ * @defgroup ivshmem ivshmem reference API
+ * @{
+ */
+
 #include <zephyr/types.h>
 #include <stddef.h>
 #include <device.h>
@@ -131,4 +137,8 @@ static inline int ivshmem_register_handler(const struct device *dev,
 }
 #endif
 
+/**
+ * @}
+ */
+
 #endif /* ZEPHYR_INCLUDE_DRIVERS_VIRTUALIZATION_IVSHMEM_H_ */