From f0febcae3da54a281cd287b2630a681ae433dddf Mon Sep 17 00:00:00 2001
From: Songqian Li <sionli@tencent.com>
Date: Thu, 29 Aug 2024 15:59:19 +0800
Subject: [PATCH] docs: add ivshmem device introduction

Signed-off-by: Songqian Li <sionli@tencent.com>
---
 docs/ivshmem.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 docs/ivshmem.md

diff --git a/docs/ivshmem.md b/docs/ivshmem.md
new file mode 100644
index 000000000..3a7913c3f
--- /dev/null
+++ b/docs/ivshmem.md
@@ -0,0 +1,51 @@
+# Inter-VM shared memory device
+
+The Inter-VM shared memory device (ivshmem) is designed to share a memory
+region between a guest and the host. In order for all guests to be able to
+pick up the shared memory area, it is modeled as a PCI device exposing said
+memory to the guest as a PCI BAR.
+
+Device Specification is
+at https://www.qemu.org/docs/master/specs/ivshmem-spec.html.
+
+Now we support setting a backend file to share data between host and guest.
+In other words, we only support ivshmem-plain and ivshmem-doorbell is not
+supported yet.
+
+## Usage
+
+`--ivshmem`, an optional argument, can be passed to enable ivshmem device.
+This argument takes a file as a `path` value and a file size as a `size` value.
+
+```
+--ivshmem <ivshmem>  device backend file "path=</path/to/a/file>,size=<file_size/must=2^n>";
+```
+
+## Example
+
+Create a file with a size bigger than passed to `cloud-hypervisor`:
+
+```
+truncate -s 1M /tmp/ivshmem.data
+```
+
+Start application to mmap the file data to a memory region:
+
+```
+./cloud-hypervisor \
+    --api-socket /tmp/cloud-hypervisor.sock \
+    --kernel vmlinux \
+    --disk path=focal-server-cloudimg-amd64.raw \
+    --cpus boot=4 \
+    --memory size=1024M \
+    --ivshmem path=/tmp/ivshmem.data,size=1M
+```
+
+Insmod a ivshmem device driver to enable the device. The file data will be
+mmapped to the PCI `bar2` of ivshmem device,
+guest can r/w data by accessing this memory.
+
+A simple example of ivshmem driver can get from:
+https://github.com/lisongqian/clh-linux/commits/ch-6.12.8-ivshmem
+
+The host process can r/w this data by remmaping the `/tmp/ivshmem.data`.