add dirty bitmap tracking abstractions

Signed-off-by: Alexandru Agache <[email protected]>

Author: alexandruag

src/bitmap.rs

@@ -0,0 +1,85 @@
+//! This module holds abstractions that enable tracking the areas dirtied by writes of a specified
+//! length to a given offset. In particular, this is used to track write accesses within a
+//! `GuestMemoryRegion` object, and the resulting bitmaps can then be aggregated to build the
+//! global view for the entire `GuestMemory`.
+
+use std::fmt::{self, Debug};
+
+/// Common bitmap operations.
+// This is just an initial proposal; we'll add other methods if they need to be part of the main
+// interface as well.
+pub trait Bitmap: Default {
+    // For now this is mostly useful to preserve compatibility with the old `GuestMemoryMmap` (and
+    // potentially other backends) constructors, which are not bitmap-aware. We can remove this
+    // from the interface (and apply changes elsewhere) if it's too restrictive and/or configuring
+    // the bitmap post-creation (via `GuestMemoryRegion::bitmap_mut`) gets unwieldy.
+    /// Create a new bitmap of the given size.
+    fn new(size: usize) -> Self;
+
+    /// Mark the memory range specified by the given `offset` and `len` as dirtied.
+    fn mark_dirty(&self, offset: usize, len: usize);
+}
+
+/// A no-op `Bitmap` implementation that can be provided to backends that do not actually
+/// require the tracking functionality.
+impl Bitmap for () {
+    fn new(_size: usize) -> Self {
+        ()
+    }
+
+    fn mark_dirty(&self, _offset: usize, _len: usize) {}
+}
+
+/// Represents a slice into a `Bitmap` object, starting at `base_offset`.
+pub struct BitmapSlice<'a, B> {
+    inner: &'a B,
+    base_offset: usize,
+}
+
+impl<'a, B: Bitmap> BitmapSlice<'a, B> {
+    /// Create a new `BitmapSlice`, starting at the specified `offset`.
+    pub fn new(bitmap: &'a B, offset: usize) -> Self {
+        BitmapSlice {
+            inner: bitmap,
+            base_offset: offset,
+        }
+    }
+
+    /// Mark the memory range specified by the given `offset` (relative to the base offset of
+    /// the slice) and `len` as dirtied.
+    pub fn mark_dirty(&self, offset: usize, len: usize) {
+        // The `Bitmap` operations are supposed to accompany guest memory accesses defined by the
+        // same parameters (i.e. offset & length), so we use simple wrapping arithmetic instead of
+        // performing additional checks. If an overflow would occur, we simply end up marking some
+        // other region as dirty (which is just a false positive) instead of a region that could
+        // not have been accessed to begin with.
+        self.inner
+            .mark_dirty(self.base_offset.wrapping_add(offset), len)
+    }
+
+    /// Create a new `BitmapSlice` starting from the specified `offset` into the current slice.
+    pub fn at_offset(&self, offset: usize) -> Self {
+        BitmapSlice {
+            inner: self.inner,
+            base_offset: self.base_offset.wrapping_add(offset),
+        }
+    }
+}
+
+impl<'a, B> Clone for BitmapSlice<'a, B> {
+    fn clone(&self) -> Self {
+        BitmapSlice {
+            inner: self.inner,
+            base_offset: self.base_offset,
+        }
+    }
+}
+
+impl<'a, B> Copy for BitmapSlice<'a, B> {}
+
+impl<'a, B> Debug for BitmapSlice<'a, B> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        // Dummy impl for now.
+        write!(f, "(bitmap slice)")
+    }
+}

src/bytes.rs

@@ -18,7 +18,6 @@ use std::slice::{from_raw_parts, from_raw_parts_mut};
 use std::sync::atomic::Ordering;
 
 use crate::atomic_integer::AtomicInteger;
-use crate::VolatileSlice;
 
 /// Types for which it is safe to initialize from raw data.
 ///
@@ -105,22 +104,6 @@ pub unsafe trait ByteValued: Copy + Default + Send + Sync {
         // borrowing the given mutable reference.
         unsafe { from_raw_parts_mut(self as *mut Self as *mut u8, size_of::<Self>()) }
     }
-
-    /// Converts a mutable reference to `self` into a `VolatileSlice`.  This is
-    /// useful because `VolatileSlice` provides a `Bytes<usize>` implementation.
-    ///
-    /// # Safety
-    ///
-    /// Unlike most `VolatileMemory` implementation, this method requires an exclusive
-    /// reference to `self`; this trivially fulfills `VolatileSlice::new`'s requirement
-    /// that all accesses to `self` use volatile accesses (because there can
-    /// be no other accesses).
-    fn as_bytes(&mut self) -> VolatileSlice {
-        unsafe {
-            // This is safe because the lifetime is the same as self
-            VolatileSlice::new(self as *mut Self as usize as *mut _, size_of::<Self>())
-        }
-    }
 }
 
 // All intrinsic types and arrays of intrinsic types are ByteValued. They are just numbers.

src/guest_memory.rs

@@ -43,6 +43,7 @@ use std::sync::atomic::Ordering;
 use std::sync::Arc;
 
 use crate::address::{Address, AddressValue};
+use crate::bitmap::Bitmap;
 use crate::bytes::{AtomicAccess, Bytes};
 use crate::volatile_memory;
 
@@ -165,6 +166,9 @@ impl FileOffset {
 /// Represents a continuous region of guest physical memory.
 #[allow(clippy::len_without_is_empty)]
 pub trait GuestMemoryRegion: Bytes<MemoryRegionAddress, E = Error> {
+    /// Type used for dirty memory tracking.
+    type B: Bitmap;
+
     /// Returns the size of the region.
     fn len(&self) -> GuestUsize;
 
@@ -177,6 +181,12 @@ pub trait GuestMemoryRegion: Bytes<MemoryRegionAddress, E = Error> {
         self.start_addr().unchecked_add(self.len() - 1)
     }
 
+    /// Borrow the associated `Bitmap` object.
+    fn bitmap(&self) -> &Self::B;
+
+    /// Mutably borrow the associated `Bitmap` object.
+    fn bitmap_mut(&mut self) -> &mut Self::B;
+
     /// Returns the given address if it is within this region.
     fn check_address(&self, addr: MemoryRegionAddress) -> Option<MemoryRegionAddress> {
         if self.address_in_range(addr) {
@@ -257,7 +267,7 @@ pub trait GuestMemoryRegion: Bytes<MemoryRegionAddress, E = Error> {
         &self,
         offset: MemoryRegionAddress,
         count: usize,
-    ) -> Result<volatile_memory::VolatileSlice> {
+    ) -> Result<volatile_memory::VolatileSlice<Self::B>> {
         Err(Error::HostAddressNotAvailable)
     }
 
@@ -285,7 +295,7 @@ pub trait GuestMemoryRegion: Bytes<MemoryRegionAddress, E = Error> {
     /// # #[cfg(feature = "backend-mmap")]
     /// # test_as_volatile_slice();
     /// ```
-    fn as_volatile_slice(&self) -> Result<volatile_memory::VolatileSlice> {
+    fn as_volatile_slice(&self) -> Result<volatile_memory::VolatileSlice<Self::B>> {
         self.get_slice(MemoryRegionAddress(0), self.len() as usize)
     }
 }
@@ -620,7 +630,8 @@ pub trait GuestMemory {
         &self,
         addr: GuestAddress,
         count: usize,
-    ) -> Result<volatile_memory::VolatileSlice> {
+    ) -> Result<volatile_memory::VolatileSlice<<<Self as GuestMemory>::R as GuestMemoryRegion>::B>>
+    {
         self.to_region_addr(addr)
             .ok_or_else(|| Error::InvalidGuestAddress(addr))
             .and_then(|(r, addr)| r.get_slice(addr, count))

src/lib.rs

@@ -31,6 +31,8 @@ pub use atomic::{GuestMemoryAtomic, GuestMemoryLoadGuard};
 mod atomic_integer;
 pub use atomic_integer::AtomicInteger;
 
+pub mod bitmap;
+
 pub mod bytes;
 pub use bytes::{AtomicAccess, ByteValued, Bytes};