shadow ioeventfd: add demo (#722)

Signed-off-by: Thanos Makatos <thanos.makatos@nutanix.com>
Reviewed-by: John Levon <john.levon@nutanix.com>

1 files changed, 31 insertions, 0 deletions

diff --git a/docs/ioregionfd.md b/docs/ioregionfd.md
index c09b077..a0cb7d7 100644
--- a/docs/ioregionfd.md
+++ b/docs/ioregionfd.md
@@ -23,3 +23,34 @@ The list of patches:
 * kernel: https://gist.github.com/tmakatos/532afd092a8df2175120d3dbfcd719ef
 * QEMU: https://gist.github.com/tmakatos/57755d2a37a6d53c9ff392e7c34470f6
 * SPDK: https://gist.github.com/tmakatos/f6c10fdaff59c9d629f94bd8e44a53bc
+
+shadow ioeventfd sample
+-----------------------
+
+samples/shadow_ioeventfd_server.c implements a vfio-user server that allows a
+part of its BAR0 to be accessed via a shadow ioeventfd.
+shadow_ioeventfd_speed_test.c is run in the guest. It compares peformance of
+shadow ioeventfd vs. vfio-user messages by repeatedly writing to the part of
+the BAR0 that is handled by shadow ioeventfd and to the part not handled by
+shadow ioeventfd.
+
+To run the sample:
+* Patch and build the kernel and QEMU using above patches.
+* Enable support for shadow ioeventfd in libvfio-user (set `shadow-ieoventfd`
+  to `true` in meson_options.txt and then build libvfio-user.
+* Run samples/shadow_ioeventfd_server, e.g.
+  ```
+  build/samples/shadow_ioeventfd_server /var/run/cntrl
+  ```
+* Start the guest with `intel_iommu=off` in the kernel command line.
+* Bind the device to VFIO:
+  ```
+  modprobe vfio-iommu-type1 allow_unsafe_interrupts=1
+  modprobe vfio-pci ids=4e58:0
+  ```
+  Build and run the test app in the guest (it needs to be copied there first),
+  the BDF needs to be substituted accordingly:
+  ```
+  gcc shadow_ioeventfd_speed_test.c
+  ./a.out 3 0000:00:03.0
+  ```