support for shadow ioeventfd

docs/ioregionfd.md

@@ -0,0 +1,16 @@
+# ioregionfd
+
+ioregionfd is a mechanism that speeds up ioeventfds:
+https://lore.kernel.org/kvm/[email protected]/. In the
+author's original words: "ioregionfd is a KVM dispatch mechanism which can be
+used for handling MMIO/PIO accesses over file descriptors without returning
+from ioctl(KVM_RUN).".
+
+libvfio-user currently supports an experimental variant of this mechanism
+called shadow ioeventfd. A shadow ioeventfd is a normal ioeventfd where the
+vfio-user server passes another piece of memory (called the _shadow_ memory)
+via an additional file descriptor when configuring the ioregionfd, which then
+QEMU memory maps and passes this address to KVM. This shadow memory is never
+exposed to the guest. When the guest writes to the trapped memory, KVM writes
+the value to the shadow memory instread of discarding it, and then proceeds
+kicking the evetnfd as normal.

include/libvfio-user.h

@@ -1069,9 +1069,9 @@ vfu_sg_is_mappable(vfu_ctx_t *vfu_ctx, dma_sg_t *sg);
  * @size: size of the ioeventfd
  * @flags: Any flags to set up the ioeventfd
  * @datamatch: sets the datamatch value
- * @shadow_fd: File descriptor than can be mmap'ed, KVM will write there the
+ * @shadow_fd: File descriptor that can be mmap'ed, KVM will write there the
  *  otherwise discarded value when the ioeventfd is written to. If set to -1
- *  then a normal ioeventfd is set up instead of a shadow one. Then vfio-user
+ *  then a normal ioeventfd is set up instead of a shadow one. The vfio-user
  *  client is free to ignore this, even if it supports shadow ioeventfds.
  *  Requires a kernel with shadow ioeventfd support.
  *  Experimental, must be compiled with SHADOW_IOEVENTFD defined, otherwise

lib/libvfio-user.c

@@ -562,7 +562,7 @@ handle_device_get_region_io_fds(vfu_ctx_t *vfu_ctx, vfu_msg_t *msg)
     ioeventfd_t *sub_reg = NULL;
     size_t nr_sub_reg = 0;
     size_t i = 0;
-    size_t nr_shdw_reg = 0;
+    size_t nr_shadow_reg = 0;
 
     assert(vfu_ctx != NULL);
     assert(msg != NULL);
@@ -594,7 +594,7 @@ handle_device_get_region_io_fds(vfu_ctx_t *vfu_ctx, vfu_msg_t *msg)
     LIST_FOREACH(sub_reg, &vfu_reg->subregions, entry) {
         nr_sub_reg++;
         if (sub_reg->shadow_fd != -1) {
-            nr_shdw_reg++;
+            nr_shadow_reg++;
         }
     }
 
@@ -625,7 +625,8 @@ handle_device_get_region_io_fds(vfu_ctx_t *vfu_ctx, vfu_msg_t *msg)
 
     msg->out.nr_fds = 0;
     if (req->argsz >= reply->argsz) {
-        msg->out.fds = calloc(sizeof(int), max_sent_sub_regions + nr_shdw_reg);
+        msg->out.fds = calloc(sizeof(int),
+                              max_sent_sub_regions + nr_shadow_reg);
         if (msg->out.fds == NULL) {
             return -1;
         }

meson_options.txt

@@ -4,5 +4,5 @@ option('tran-pipe', type: 'boolean', value: false,
        description: 'enable pipe transport for testing')
 option('debug-logs', type: 'feature', value: 'auto',
        description: 'enable extra debugging code (default for debug builds)')
-option('shadow-ioeventfd', type: 'boolean', value : true,
+option('shadow-ioeventfd', type: 'boolean', value : false,
        description: 'enable shadow ioeventfd (experimental)')

test/py/meson.build

@@ -49,8 +49,7 @@ python_tests = [
     'test_vfu_realize_ctx.py',
 ]
 
-opt_shadow_ioeventfd = get_option('shadow-ioeventfd')
-if opt_shadow_ioeventfd
+if get_option('shadow-ioeventfd')
     python_tests += 'test_shadow_ioeventfd.py'
 endif
 

test/py/test_shadow_ioeventfd.py

@@ -91,7 +91,7 @@ def test_shadow_ioeventfd():
     else:
         assert False
 
-    # Client writes to the I/O region. Tthe write to the eventfd would by done
+    # Client writes to the I/O region. The write to the eventfd would be done
     # by KVM and the value would be the same in both cases.
     cmem.seek(0x8)
     cmem.write(c.c_ulonglong(0xdeadbeef))