kvm-ioctls: Implement dirty ring interface

Added `dirty_log_ring_iter` to access iterator of dirty
pages. Implement rest of dirty log ring interface,
including `enable_dirty_log_ring` and subsequent automatic
mapping of `KvmDirtyLogRing` for new vcpus.

Signed-off-by: David Kleymann <[email protected]>

Author: David Kleymann

kvm-ioctls/CHANGELOG.md

@@ -6,7 +6,14 @@
 
 - Added `KvmDirtyLogRing` structure to mmap the dirty log ring.
 - Added `KVM_DIRTY_GFN_F_DIRTY` and `KVM_DIRTY_GFN_F_RESET` bitflags.
-
+- Added `KvmDirtyLogRing` iterator type for accessing dirty log entries.
+- Added `dirty_log_ring` field to `VcpuFd` to access per-vCpu dirty rings.
+- Added `dirty_log_bytes` field to `VmFd` to automatically map correct size dirty
+  rings for vCpus as they are created.
+- Added `enable_dirty_log_ring` function on `VmFd` to check corresponding 
+  capabilities and enable KVM's dirty log ring.
+- Added `VcpuFd::dirty_log_ring_iter()` to iterate over dirty guest frame numbers.
+- Added `VmFd::reset_dirty_rings()` to reset all dirty rings for the VM.
 
 - Plumb through KVM_CAP_DIRTY_LOG_RING as DirtyLogRing cap.
 

kvm-ioctls/src/ioctls/vcpu.rs

@@ -16,7 +16,7 @@ use libc::EINVAL;
 use std::fs::File;
 use std::os::unix::io::{AsRawFd, RawFd};
 
-use crate::ioctls::{KvmCoalescedIoRing, KvmRunWrapper, Result};
+use crate::ioctls::{KvmCoalescedIoRing, KvmDirtyLogRing, KvmRunWrapper, Result};
 use crate::kvm_ioctls::*;
 use vmm_sys_util::errno;
 use vmm_sys_util::ioctl::{ioctl, ioctl_with_mut_ref, ioctl_with_ref};
@@ -197,6 +197,9 @@ pub struct VcpuFd {
     kvm_run_ptr: KvmRunWrapper,
     /// A pointer to the coalesced MMIO page
     coalesced_mmio_ring: Option<KvmCoalescedIoRing>,
+    /// A pointer to the dirty log ring
+    #[cfg(target_arch = "x86_64")]
+    dirty_log_ring: Option<KvmDirtyLogRing>,
 }
 
 /// KVM Sync Registers used to tell KVM which registers to sync
@@ -2104,6 +2107,38 @@ impl VcpuFd {
         }
     }
 
+    /// Gets the dirty log ring iterator if one is mapped.
+    ///
+    /// Returns an iterator over dirty guest frame numbers as (slot, offset) tuples.
+    /// Returns `None` if no dirty log ring has been mapped via [`map_dirty_log_ring`](VcpuFd::map_dirty_log_ring).
+    ///
+    /// # Returns
+    ///
+    /// An optional iterator over the dirty log ring entries.
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// # use kvm_ioctls::Kvm;
+    /// # use kvm_ioctls::Cap;
+    /// let kvm = Kvm::new().unwrap();
+    /// let vm = kvm.create_vm().unwrap();
+    /// vm.enable_dirty_log_ring(None).unwrap();
+    /// let mut vcpu = vm.create_vcpu(0).unwrap();
+    /// if kvm.check_extension(Cap::DirtyLogRing) {
+    ///     if let Some(mut iter) = vcpu.dirty_log_ring_iter() {
+    ///         for (slot, offset) in iter {
+    ///             println!("Dirty page in slot {} at offset {}", slot, offset);
+    ///         }
+    ///     }
+    /// }
+    /// ```
+    ///
+    #[cfg(target_arch = "x86_64")]
+    pub fn dirty_log_ring_iter(&mut self) -> Option<impl Iterator<Item = (u32, u64)>> {
+        self.dirty_log_ring.as_mut()
+    }
+
     /// Maps the coalesced MMIO ring page. This allows reading entries from
     /// the ring via [`coalesced_mmio_read()`](VcpuFd::coalesced_mmio_read).
     ///
@@ -2159,11 +2194,16 @@ impl VcpuFd {
 /// This should not be exported as a public function because the preferred way is to use
 /// `create_vcpu` from `VmFd`. The function cannot be part of the `VcpuFd` implementation because
 /// then it would be exported with the public `VcpuFd` interface.
-pub fn new_vcpu(vcpu: File, kvm_run_ptr: KvmRunWrapper) -> VcpuFd {
+pub fn new_vcpu(
+    vcpu: File,
+    kvm_run_ptr: KvmRunWrapper,
+    dirty_log_ring: Option<KvmDirtyLogRing>,
+) -> VcpuFd {
     VcpuFd {
         vcpu,
         kvm_run_ptr,
         coalesced_mmio_ring: None,
+        dirty_log_ring: dirty_log_ring,
     }
 }
 

kvm-ioctls/src/ioctls/vm.rs

@@ -18,7 +18,7 @@ use crate::ioctls::device::DeviceFd;
 use crate::ioctls::device::new_device;
 use crate::ioctls::vcpu::VcpuFd;
 use crate::ioctls::vcpu::new_vcpu;
-use crate::ioctls::{KvmRunWrapper, Result};
+use crate::ioctls::{KvmDirtyLogRing, KvmRunWrapper, Result};
 use crate::kvm_ioctls::*;
 use vmm_sys_util::errno;
 use vmm_sys_util::eventfd::EventFd;
@@ -59,6 +59,7 @@ impl From<NoDatamatch> for u64 {
 pub struct VmFd {
     vm: File,
     run_size: usize,
+    dirty_ring_bytes: usize,
 }
 
 impl VmFd {
@@ -1214,7 +1215,15 @@ impl VmFd {
 
         let kvm_run_ptr = KvmRunWrapper::mmap_from_fd(&vcpu, self.run_size)?;
 
-        Ok(new_vcpu(vcpu, kvm_run_ptr))
+        let dirty_log_ring = {
+            if self.dirty_ring_bytes > 0 {
+                Some(KvmDirtyLogRing::mmap_from_fd(&vcpu, self.dirty_ring_bytes)?)
+            } else {
+                None
+            }
+        };
+
+        Ok(new_vcpu(vcpu, kvm_run_ptr, dirty_log_ring))
     }
 
     /// Creates a VcpuFd object from a vcpu RawFd.
@@ -1250,7 +1259,14 @@ impl VmFd {
         // SAFETY: we trust the kernel and verified parameters
         let vcpu = unsafe { File::from_raw_fd(fd) };
         let kvm_run_ptr = KvmRunWrapper::mmap_from_fd(&vcpu, self.run_size)?;
-        Ok(new_vcpu(vcpu, kvm_run_ptr))
+        let dirty_log_ring = {
+            if self.dirty_ring_bytes > 0 {
+                Some(KvmDirtyLogRing::mmap_from_fd(&vcpu, self.dirty_ring_bytes)?)
+            } else {
+                None
+            }
+        };
+        Ok(new_vcpu(vcpu, kvm_run_ptr, dirty_log_ring))
     }
 
     /// Creates an emulated device in the kernel.
@@ -1915,6 +1931,108 @@ impl VmFd {
         Ok(())
     }
 
+    /// Enables KVM's dirty log ring for new vCPUs created on this VM. Checks required capabilities and returns
+    /// `true` if the ring needs to be used together with a backup bitmap `KVM_GET_DIRTY_LOG`. Takes optional
+    /// dirty ring size as bytes, if not supplied, will use maximum supported dirty ring size. Enabling the dirty
+    /// log ring is only allowed before any vCPU was created on the VmFd.
+    /// # Arguments
+    ///
+    /// * `bytes` - Size of the dirty log ring in bytes. Needs to be multiple of `std::mem::size_of::<kvm_dirty_gfn>()`
+    /// and power of two.
+    #[cfg(target_arch = "x86_64")]
+    pub fn enable_dirty_log_ring(&self, bytes: Option<i32>) -> Result<bool> {
+        // Check if requested size is larger than 0
+        if let Some(sz) = bytes {
+            if sz <= 0
+                || !(sz as u32).is_power_of_two()
+                || (sz as usize % std::mem::size_of::<kvm_dirty_gfn>() == 0)
+            {
+                return Err(errno::Error::new(libc::EINVAL));
+            }
+        }
+
+        let (dirty_ring_cap, max_bytes, bitmap) = {
+            // Check if KVM_CAP_DIRTY_LOG_RING_ACQ_REL is available, enable if possible
+            let acq_rel_sz = self.check_extension_raw(KVM_CAP_DIRTY_LOG_RING_ACQ_REL.into());
+            if acq_rel_sz > 0 {
+                if self.check_extension_raw(KVM_CAP_DIRTY_LOG_RING_WITH_BITMAP.into()) != 0 {
+                    (KVM_CAP_DIRTY_LOG_RING_ACQ_REL, acq_rel_sz, true)
+                } else {
+                    (KVM_CAP_DIRTY_LOG_RING_ACQ_REL, acq_rel_sz, false)
+                }
+            } else {
+                let sz = self.check_extension_raw(KVM_CAP_DIRTY_LOG_RING.into());
+                if sz > 0 {
+                    (KVM_CAP_DIRTY_LOG_RING, sz, false)
+                } else {
+                    (0, 0, false)
+                }
+            }
+        };
+
+        if dirty_ring_cap == 0 {
+            // Neither KVM_CAP_DIRTY_LOG_RING nor KVM_CAP_DIRTY_LOG_RING_ACQ_REL are available
+            return Err(errno::Error::new(libc::EOPNOTSUPP));
+        }
+
+        let cap_ring_size = bytes.unwrap_or(max_bytes);
+
+        // Check if supplied size is larger than what the kernel supports
+        if cap_ring_size > max_bytes {
+            return Err(errno::Error::new(libc::EINVAL));
+        }
+
+        // Enable dirty rings with _ACQ_REL if supported, or without otherwise
+        let ar_ring_cap = kvm_enable_cap {
+            cap: dirty_ring_cap,
+            args: [cap_ring_size as u64, 0, 0, 0],
+            ..Default::default()
+        };
+
+        // Enable the ring cap first
+        self.enable_cap(&ar_ring_cap)?;
+
+        if bitmap {
+            let with_bitmap_cap = kvm_enable_cap {
+                cap: KVM_CAP_DIRTY_LOG_RING_WITH_BITMAP,
+                ..Default::default()
+            };
+
+            // Enable backup bitmap
+            self.enable_cap(&with_bitmap_cap)?;
+        }
+
+        Ok(bitmap)
+    }
+
+    /// Resets all vCPU's dirty log rings. This notifies the kernel that pages have been harvested
+    /// from the dirty ring and the corresponding pages can be reprotected.
+    ///
+    /// # Example
+    ///
+    ///  ```rust
+    /// # extern crate kvm_ioctls;
+    /// # use kvm_ioctls::{Cap, Kvm};
+    /// let kvm = Kvm::new().unwrap();
+    /// let vm = kvm.create_vm().unwrap();
+    /// vm.enable_dirty_log_ring(None).unwrap();
+    /// if kvm.check_extension(Cap::DirtyLogRing) {
+    ///     vm.reset_dirty_rings().unwrap();
+    /// }
+    /// ```
+    ///
+    #[cfg(target_arch = "x86_64")]
+    pub fn reset_dirty_rings(&self) -> Result<c_int> {
+        // SAFETY: Safe because we know that our file is a KVM fd and that the request is one of
+        // the ones defined by kernel.
+        let ret = unsafe { ioctl(self, KVM_RESET_DIRTY_RINGS()) };
+        if ret < 0 {
+            Err(errno::Error::last())
+        } else {
+            Ok(ret)
+        }
+    }
+
     /// Sets a specified piece of vm configuration and/or state.
     ///
     /// See the documentation for `KVM_SET_DEVICE_ATTR` in
@@ -2011,7 +2129,11 @@ impl VmFd {
 /// `create_vm` from `Kvm`. The function cannot be part of the `VmFd` implementation because
 /// then it would be exported with the public `VmFd` interface.
 pub fn new_vmfd(vm: File, run_size: usize) -> VmFd {
-    VmFd { vm, run_size }
+    VmFd {
+        vm,
+        run_size,
+        dirty_ring_bytes: 0,
+    }
 }
 
 impl AsRawFd for VmFd {
@@ -2601,6 +2723,7 @@ mod tests {
         let faulty_vm_fd = VmFd {
             vm: unsafe { File::from_raw_fd(-2) },
             run_size: 0,
+            dirty_ring_bytes: 0,
         };
 
         let invalid_mem_region = kvm_userspace_memory_region {

kvm-ioctls/src/kvm_ioctls.rs

@@ -220,6 +220,8 @@ ioctl_io_nr!(KVM_SET_TSC_KHZ, KVMIO, 0xa2);
 /* Available with KVM_CAP_GET_TSC_KHZ */
 #[cfg(target_arch = "x86_64")]
 ioctl_io_nr!(KVM_GET_TSC_KHZ, KVMIO, 0xa3);
+/* Available with KVM_CAP_DIRTY_LOG_RING */
+ioctl_io_nr!(KVM_RESET_DIRTY_RINGS, KVMIO, 0xc7);
 
 /* Available with KVM_CAP_ENABLE_CAP */
 #[cfg(not(any(target_arch = "aarch64", target_arch = "riscv64")))]