introduce region module

This modules is intended for all functionality that relates to
contiguous regions of guest memory. This differentiates it from
`guest_memory`, as that is about a holistic view of guest memory, and
from `mmap`, which is specifically about guest memory regions backed by
mmap VMAs.

Signed-off-by: Patrick Roy <roypat@amazon.co.uk>

Author: roypat

src/guest_memory.rs

@@ -50,10 +50,11 @@ use std::sync::atomic::Ordering;
 use std::sync::Arc;
 
 use crate::address::{Address, AddressValue};
-use crate::bitmap::{Bitmap, BS, MS};
+use crate::bitmap::MS;
 use crate::bytes::{AtomicAccess, Bytes};
 use crate::io::{ReadVolatile, WriteVolatile};
 use crate::volatile_memory::{self, VolatileSlice};
+use crate::GuestMemoryRegion;
 
 /// Errors associated with handling guest memory accesses.
 #[allow(missing_docs)]
@@ -158,139 +159,6 @@ 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;
-
-    /// Returns the minimum (inclusive) address managed by the region.
-    fn start_addr(&self) -> GuestAddress;
-
-    /// Returns the maximum (inclusive) address managed by the region.
-    fn last_addr(&self) -> GuestAddress {
-        // unchecked_add is safe as the region bounds were checked when it was created.
-        self.start_addr().unchecked_add(self.len() - 1)
-    }
-
-    /// Borrow the associated `Bitmap` object.
-    fn bitmap(&self) -> &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) {
-            Some(addr)
-        } else {
-            None
-        }
-    }
-
-    /// Returns `true` if the given address is within this region.
-    fn address_in_range(&self, addr: MemoryRegionAddress) -> bool {
-        addr.raw_value() < self.len()
-    }
-
-    /// Returns the address plus the offset if it is in this region.
-    fn checked_offset(
-        &self,
-        base: MemoryRegionAddress,
-        offset: usize,
-    ) -> Option<MemoryRegionAddress> {
-        base.checked_add(offset as u64)
-            .and_then(|addr| self.check_address(addr))
-    }
-
-    /// Tries to convert an absolute address to a relative address within this region.
-    ///
-    /// Returns `None` if `addr` is out of the bounds of this region.
-    fn to_region_addr(&self, addr: GuestAddress) -> Option<MemoryRegionAddress> {
-        addr.checked_offset_from(self.start_addr())
-            .and_then(|offset| self.check_address(MemoryRegionAddress(offset)))
-    }
-
-    /// Returns the host virtual address corresponding to the region address.
-    ///
-    /// Some [`GuestMemory`](trait.GuestMemory.html) implementations, like `GuestMemoryMmap`,
-    /// have the capability to mmap guest address range into host virtual address space for
-    /// direct access, so the corresponding host virtual address may be passed to other subsystems.
-    ///
-    /// # Note
-    /// The underlying guest memory is not protected from memory aliasing, which breaks the
-    /// Rust memory safety model. It's the caller's responsibility to ensure that there's no
-    /// concurrent accesses to the underlying guest memory.
-    fn get_host_address(&self, _addr: MemoryRegionAddress) -> Result<*mut u8> {
-        Err(Error::HostAddressNotAvailable)
-    }
-
-    /// Returns information regarding the file and offset backing this memory region.
-    fn file_offset(&self) -> Option<&FileOffset> {
-        None
-    }
-
-    /// Returns a [`VolatileSlice`](struct.VolatileSlice.html) of `count` bytes starting at
-    /// `offset`.
-    #[allow(unused_variables)]
-    fn get_slice(
-        &self,
-        offset: MemoryRegionAddress,
-        count: usize,
-    ) -> Result<VolatileSlice<BS<Self::B>>> {
-        Err(Error::HostAddressNotAvailable)
-    }
-
-    /// Gets a slice of memory for the entire region that supports volatile access.
-    ///
-    /// # Examples (uses the `backend-mmap` feature)
-    ///
-    /// ```
-    /// # #[cfg(feature = "backend-mmap")]
-    /// # {
-    /// # use vm_memory::{GuestAddress, MmapRegion, GuestRegionMmap, GuestMemoryRegion};
-    /// # use vm_memory::volatile_memory::{VolatileMemory, VolatileSlice, VolatileRef};
-    /// #
-    /// let region = GuestRegionMmap::<()>::from_range(GuestAddress(0x0), 0x400, None)
-    ///     .expect("Could not create guest memory");
-    /// let slice = region
-    ///     .as_volatile_slice()
-    ///     .expect("Could not get volatile slice");
-    ///
-    /// let v = 42u32;
-    /// let r = slice
-    ///     .get_ref::<u32>(0x200)
-    ///     .expect("Could not get reference");
-    /// r.store(v);
-    /// assert_eq!(r.load(), v);
-    /// # }
-    /// ```
-    fn as_volatile_slice(&self) -> Result<VolatileSlice<BS<Self::B>>> {
-        self.get_slice(MemoryRegionAddress(0), self.len() as usize)
-    }
-
-    /// Show if the region is based on the `HugeTLBFS`.
-    /// Returns Some(true) if the region is backed by hugetlbfs.
-    /// None represents that no information is available.
-    ///
-    /// # Examples (uses the `backend-mmap` feature)
-    ///
-    /// ```
-    /// # #[cfg(feature = "backend-mmap")]
-    /// # {
-    /// #   use vm_memory::{GuestAddress, GuestMemory, GuestMemoryMmap, GuestRegionMmap};
-    /// let addr = GuestAddress(0x1000);
-    /// let mem = GuestMemoryMmap::<()>::from_ranges(&[(addr, 0x1000)]).unwrap();
-    /// let r = mem.find_region(addr).unwrap();
-    /// assert_eq!(r.is_hugetlbfs(), None);
-    /// # }
-    /// ```
-    #[cfg(target_os = "linux")]
-    fn is_hugetlbfs(&self) -> Option<bool> {
-        None
-    }
-}
-
 /// `GuestAddressSpace` provides a way to retrieve a `GuestMemory` object.
 /// The vm-memory crate already provides trivial implementation for
 /// references to `GuestMemory` or reference-counted `GuestMemory` objects,
@@ -409,7 +277,8 @@ pub trait GuestMemory {
 
     /// Returns the region containing the specified address or `None`.
     fn find_region(&self, addr: GuestAddress) -> Option<&Self::R> {
-        self.iter().find(|region| addr >= region.start_addr() && addr <= region.last_addr())
+        self.iter()
+            .find(|region| addr >= region.start_addr() && addr <= region.last_addr())
     }
 
     /// Gets an iterator over the entries in the collection.

src/lib.rs

@@ -47,9 +47,12 @@ pub use endian::{Be16, Be32, Be64, BeSize, Le16, Le32, Le64, LeSize};
 pub mod guest_memory;
 pub use guest_memory::{
     Error as GuestMemoryError, FileOffset, GuestAddress, GuestAddressSpace, GuestMemory,
-    GuestMemoryRegion, GuestUsize, MemoryRegionAddress, Result as GuestMemoryResult,
+    GuestUsize, MemoryRegionAddress, Result as GuestMemoryResult,
 };
 
+pub mod region;
+pub use region::GuestMemoryRegion;
+
 pub mod io;
 pub use io::{ReadVolatile, WriteVolatile};
 

src/mmap.rs

@@ -23,8 +23,9 @@ use std::sync::Arc;
 use crate::address::Address;
 use crate::bitmap::{Bitmap, BS};
 use crate::guest_memory::{
-    self, FileOffset, GuestAddress, GuestMemory, GuestMemoryRegion, GuestUsize, MemoryRegionAddress,
+    self, FileOffset, GuestAddress, GuestMemory, GuestUsize, MemoryRegionAddress,
 };
+use crate::region::GuestMemoryRegion;
 use crate::volatile_memory::{VolatileMemory, VolatileSlice};
 use crate::{AtomicAccess, Bytes, ReadVolatile, WriteVolatile};
 

src/region.rs

@@ -0,0 +1,141 @@
+//! Module containing abstracts for dealing with contiguous regions of guest memory
+
+use crate::bitmap::{Bitmap, BS};
+use crate::guest_memory::Error;
+use crate::guest_memory::Result;
+use crate::{
+    Address, Bytes, FileOffset, GuestAddress, GuestUsize, MemoryRegionAddress, VolatileSlice,
+};
+
+/// 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;
+
+    /// Returns the minimum (inclusive) address managed by the region.
+    fn start_addr(&self) -> GuestAddress;
+
+    /// Returns the maximum (inclusive) address managed by the region.
+    fn last_addr(&self) -> GuestAddress {
+        // unchecked_add is safe as the region bounds were checked when it was created.
+        self.start_addr().unchecked_add(self.len() - 1)
+    }
+
+    /// Borrow the associated `Bitmap` object.
+    fn bitmap(&self) -> &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) {
+            Some(addr)
+        } else {
+            None
+        }
+    }
+
+    /// Returns `true` if the given address is within this region.
+    fn address_in_range(&self, addr: MemoryRegionAddress) -> bool {
+        addr.raw_value() < self.len()
+    }
+
+    /// Returns the address plus the offset if it is in this region.
+    fn checked_offset(
+        &self,
+        base: MemoryRegionAddress,
+        offset: usize,
+    ) -> Option<MemoryRegionAddress> {
+        base.checked_add(offset as u64)
+            .and_then(|addr| self.check_address(addr))
+    }
+
+    /// Tries to convert an absolute address to a relative address within this region.
+    ///
+    /// Returns `None` if `addr` is out of the bounds of this region.
+    fn to_region_addr(&self, addr: GuestAddress) -> Option<MemoryRegionAddress> {
+        addr.checked_offset_from(self.start_addr())
+            .and_then(|offset| self.check_address(MemoryRegionAddress(offset)))
+    }
+
+    /// Returns the host virtual address corresponding to the region address.
+    ///
+    /// Some [`GuestMemory`](trait.GuestMemory.html) implementations, like `GuestMemoryMmap`,
+    /// have the capability to mmap guest address range into host virtual address space for
+    /// direct access, so the corresponding host virtual address may be passed to other subsystems.
+    ///
+    /// # Note
+    /// The underlying guest memory is not protected from memory aliasing, which breaks the
+    /// Rust memory safety model. It's the caller's responsibility to ensure that there's no
+    /// concurrent accesses to the underlying guest memory.
+    fn get_host_address(&self, _addr: MemoryRegionAddress) -> Result<*mut u8> {
+        Err(Error::HostAddressNotAvailable)
+    }
+
+    /// Returns information regarding the file and offset backing this memory region.
+    fn file_offset(&self) -> Option<&FileOffset> {
+        None
+    }
+
+    /// Returns a [`VolatileSlice`](struct.VolatileSlice.html) of `count` bytes starting at
+    /// `offset`.
+    #[allow(unused_variables)]
+    fn get_slice(
+        &self,
+        offset: MemoryRegionAddress,
+        count: usize,
+    ) -> Result<VolatileSlice<BS<Self::B>>> {
+        Err(Error::HostAddressNotAvailable)
+    }
+
+    /// Gets a slice of memory for the entire region that supports volatile access.
+    ///
+    /// # Examples (uses the `backend-mmap` feature)
+    ///
+    /// ```
+    /// # #[cfg(feature = "backend-mmap")]
+    /// # {
+    /// # use vm_memory::{GuestAddress, MmapRegion, GuestRegionMmap, GuestMemoryRegion};
+    /// # use vm_memory::volatile_memory::{VolatileMemory, VolatileSlice, VolatileRef};
+    /// #
+    /// let region = GuestRegionMmap::<()>::from_range(GuestAddress(0x0), 0x400, None)
+    ///     .expect("Could not create guest memory");
+    /// let slice = region
+    ///     .as_volatile_slice()
+    ///     .expect("Could not get volatile slice");
+    ///
+    /// let v = 42u32;
+    /// let r = slice
+    ///     .get_ref::<u32>(0x200)
+    ///     .expect("Could not get reference");
+    /// r.store(v);
+    /// assert_eq!(r.load(), v);
+    /// # }
+    /// ```
+    fn as_volatile_slice(&self) -> Result<VolatileSlice<BS<Self::B>>> {
+        self.get_slice(MemoryRegionAddress(0), self.len() as usize)
+    }
+
+    /// Show if the region is based on the `HugeTLBFS`.
+    /// Returns Some(true) if the region is backed by hugetlbfs.
+    /// None represents that no information is available.
+    ///
+    /// # Examples (uses the `backend-mmap` feature)
+    ///
+    /// ```
+    /// # #[cfg(feature = "backend-mmap")]
+    /// # {
+    /// #   use vm_memory::{GuestAddress, GuestMemory, GuestMemoryMmap, GuestRegionMmap};
+    /// let addr = GuestAddress(0x1000);
+    /// let mem = GuestMemoryMmap::<()>::from_ranges(&[(addr, 0x1000)]).unwrap();
+    /// let r = mem.find_region(addr).unwrap();
+    /// assert_eq!(r.is_hugetlbfs(), None);
+    /// # }
+    /// ```
+    #[cfg(target_os = "linux")]
+    fn is_hugetlbfs(&self) -> Option<bool> {
+        None
+    }
+}