Generalize GuestMemoryMmap to arbitrary GuestMemoryRegions

Add the concept of a `GuestRegionCollection`, which just manages a list
of some `GuestMemoryRegion` impls. Functionality wise, it offers the
same implementations as `GuestMemoryMmap`. As a result, turn
`GuestMemoryMmap` into a type alias for `GuestRegionCollection` with a
fixed `R = GuestRegionMmap`.

The error type handling is a bit wack, but this is needed to preserve
backwards compatibility: The error type of GuestRegionCollection must
match what GuestMemoryMmap historically returned, so the error type
needs to be lifted from mmap.rs - however, it contains specific variants
that are only relevant to GuestMemoryMmap, so cfg those behind the
`backend-mmap` feature flag (as to why this specific error type gets be
privilege of just being reexported as `Error` from this crate: No idea,
but its pre-existing, and changing it would be a breaking change).

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

Author: roypat

CHANGELOG.md

@@ -5,6 +5,8 @@
 ### Added
 
 - \[[#311](https://github.com/rust-vmm/vm-memory/pull/311)\] Allow compiling without the ReadVolatile and WriteVolatile implementations
+- \[[#312](https://github.com/rust-vmm/vm-memory/pull/312)\] `GuestRegionContainer`, a generic container of `GuestMemoryRegion`s, generalizing `GuestMemoryMmap` (which 
+  is now a type alias for `GuestRegionContainer<GuestRegionMmap>`)
 
 ### Changed
 

src/guest_memory.rs

@@ -409,7 +409,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.
@@ -586,6 +587,168 @@ pub trait GuestMemory {
     }
 }
 
+/// Errors that can occur when creating a memory map.
+#[derive(Debug, thiserror::Error)]
+pub enum GuestRegionCollectionError {
+    /// Adding the guest base address to the length of the underlying mapping resulted
+    /// in an overflow.
+    #[error("Adding the guest base address to the length of the underlying mapping resulted in an overflow")]
+    #[cfg(feature = "backend-mmap")]
+    InvalidGuestRegion,
+    /// Error creating a `MmapRegion` object.
+    #[error("{0}")]
+    #[cfg(feature = "backend-mmap")]
+    MmapRegion(crate::mmap::MmapRegionError),
+    /// No memory region found.
+    #[error("No memory region found")]
+    NoMemoryRegion,
+    /// Some of the memory regions intersect with each other.
+    #[error("Some of the memory regions intersect with each other")]
+    MemoryRegionOverlap,
+    /// The provided memory regions haven't been sorted.
+    #[error("The provided memory regions haven't been sorted")]
+    UnsortedMemoryRegions,
+}
+
+/// [`GuestMemory`](trait.GuestMemory.html) implementation based on a homogeneous collection
+/// of [`GuestMemoryRegion`] implementations.
+///
+/// Represents a sorted set of non-overlapping physical guest memory regions.
+#[derive(Debug)]
+pub struct GuestRegionCollection<R: GuestMemoryRegion> {
+    regions: Vec<Arc<R>>,
+}
+
+impl<R: GuestMemoryRegion> Default for GuestRegionCollection<R> {
+    fn default() -> Self {
+        Self {
+            regions: Vec::new(),
+        }
+    }
+}
+
+impl<R: GuestMemoryRegion> Clone for GuestRegionCollection<R> {
+    fn clone(&self) -> Self {
+        GuestRegionCollection {
+            regions: self.regions.iter().map(Arc::clone).collect(),
+        }
+    }
+}
+
+impl<R: GuestMemoryRegion> GuestRegionCollection<R> {
+    /// Creates an empty `GuestMemoryMmap` instance.
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Creates a new [`GuestRegionCollection`] from a vector of regions.
+    ///
+    /// # Arguments
+    ///
+    /// * `regions` - The vector of regions.
+    ///               The regions shouldn't overlap, and they should be sorted
+    ///               by the starting address.
+    pub fn from_regions(
+        mut regions: Vec<R>,
+    ) -> std::result::Result<Self, GuestRegionCollectionError> {
+        Self::from_arc_regions(regions.drain(..).map(Arc::new).collect())
+    }
+
+    /// Creates a new [`GuestRegionCollection`] from a vector of Arc regions.
+    ///
+    /// Similar to the constructor `from_regions()` as it returns a
+    /// [`GuestRegionCollection`]. The need for this constructor is to provide a way for
+    /// consumer of this API to create a new [`GuestRegionCollection`] based on existing
+    /// regions coming from an existing [`GuestRegionCollection`] instance.
+    ///
+    /// # Arguments
+    ///
+    /// * `regions` - The vector of `Arc` regions.
+    ///               The regions shouldn't overlap and they should be sorted
+    ///               by the starting address.
+    pub fn from_arc_regions(
+        regions: Vec<Arc<R>>,
+    ) -> std::result::Result<Self, GuestRegionCollectionError> {
+        if regions.is_empty() {
+            return Err(GuestRegionCollectionError::NoMemoryRegion);
+        }
+
+        for window in regions.windows(2) {
+            let prev = &window[0];
+            let next = &window[1];
+
+            if prev.start_addr() > next.start_addr() {
+                return Err(GuestRegionCollectionError::UnsortedMemoryRegions);
+            }
+
+            if prev.last_addr() >= next.start_addr() {
+                return Err(GuestRegionCollectionError::MemoryRegionOverlap);
+            }
+        }
+
+        Ok(Self { regions })
+    }
+
+    /// Insert a region into the `GuestMemoryMmap` object and return a new `GuestMemoryMmap`.
+    ///
+    /// # Arguments
+    /// * `region`: the memory region to insert into the guest memory object.
+    pub fn insert_region(
+        &self,
+        region: Arc<R>,
+    ) -> std::result::Result<GuestRegionCollection<R>, GuestRegionCollectionError> {
+        let mut regions = self.regions.clone();
+        regions.push(region);
+        regions.sort_by_key(|x| x.start_addr());
+
+        Self::from_arc_regions(regions)
+    }
+
+    /// Remove a region from the [`GuestRegionCollection`] object and return a new `GuestRegionCollection`
+    /// on success, together with the removed region.
+    ///
+    /// # Arguments
+    /// * `base`: base address of the region to be removed
+    /// * `size`: size of the region to be removed
+    pub fn remove_region(
+        &self,
+        base: GuestAddress,
+        size: GuestUsize,
+    ) -> std::result::Result<(GuestRegionCollection<R>, Arc<R>), GuestRegionCollectionError> {
+        if let Ok(region_index) = self.regions.binary_search_by_key(&base, |x| x.start_addr()) {
+            if self.regions.get(region_index).unwrap().len() == size {
+                let mut regions = self.regions.clone();
+                let region = regions.remove(region_index);
+                return Ok((Self { regions }, region));
+            }
+        }
+
+        Err(GuestRegionCollectionError::NoMemoryRegion)
+    }
+}
+
+impl<R: GuestMemoryRegion> GuestMemory for GuestRegionCollection<R> {
+    type R = R;
+
+    fn num_regions(&self) -> usize {
+        self.regions.len()
+    }
+
+    fn find_region(&self, addr: GuestAddress) -> Option<&R> {
+        let index = match self.regions.binary_search_by_key(&addr, |x| x.start_addr()) {
+            Ok(x) => Some(x),
+            // Within the closest region with starting address < addr
+            Err(x) if (x > 0 && addr <= self.regions[x - 1].last_addr()) => Some(x - 1),
+            _ => None,
+        };
+        index.map(|x| self.regions[x].as_ref())
+    }
+
+    fn iter(&self) -> impl Iterator<Item = &Self::R> {
+        self.regions.iter().map(AsRef::as_ref)
+    }
+}
+
 impl<T: GuestMemory + ?Sized> Bytes<GuestAddress> for T {
     type E = Error;
 

src/lib.rs

@@ -47,7 +47,8 @@ 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,
+    GuestMemoryRegion, GuestRegionCollection, GuestRegionCollectionError as Error, GuestUsize,
+    MemoryRegionAddress, Result as GuestMemoryResult,
 };
 
 pub mod io;
@@ -66,7 +67,7 @@ mod mmap_windows;
 pub mod mmap;
 
 #[cfg(feature = "backend-mmap")]
-pub use mmap::{Error, GuestMemoryMmap, GuestRegionMmap, MmapRegion};
+pub use mmap::{GuestMemoryMmap, GuestRegionMmap, MmapRegion};
 #[cfg(all(feature = "backend-mmap", feature = "xen", unix))]
 pub use mmap::{MmapRange, MmapXenFlags};