guest_memory: introduce GuestAddressSpace

This provides a way for devices to access memory independent on
how the whole program stores the memory map.  To do so, devices
use GuestAddressSpace instead of something like &'a M or Arc<M>,
so that the VMM can optionally define a smart pointer that will guard
accesses to the memory; for example, the result of memory() could
be a lock guard such as a RwLockReadGuard.  This would not be very
scalable but it would be simple.

If the VMM instead uses an immutable memory map, i.e. a GuestMemory,
vm-memory already provides trivial implementations of the trait that works
for both references and reference-counted objects.  For references,
the implementation imposes no abstraction cost on device that use
GuestAddressSpace<M> instead of &'a M.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>

Author: bonzini

src/guest_memory.rs

@@ -26,12 +26,17 @@
 //!     - hide the detail of accessing guest's physical address.
 //!     - map a request address to a GuestMemoryRegion object and relay the request to it.
 //!     - handle cases where an access request spanning two or more GuestMemoryRegion objects.
+//!
+//! Whenever a collection of GuestMemoryRegion objects is mutable,
+//! [GuestAddressSpace](trait.GuestAddressSpace.html) should be implemented
+//! for clients to obtain a [GuestMemory] reference or smart pointer.
 
 use std::convert::From;
 use std::fmt::{self, Display};
 use std::fs::File;
 use std::io::{self, Read, Write};
-use std::ops::{BitAnd, BitOr};
+use std::ops::{BitAnd, BitOr, Deref};
+use std::rc::Rc;
 use std::sync::Arc;
 
 use crate::address::{Address, AddressValue};
@@ -243,14 +248,104 @@ pub trait GuestMemoryRegion: Bytes<MemoryRegionAddress, E = Error> {
     }
 }
 
-/// Represents a container for a collection of GuestMemoryRegion objects.
+/// 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,
+/// but the trait can also be implemented by any other struct in order
+/// to provide temporary access to a snapshot of the memory map.
+///
+/// In order to support generic mutable memory maps, devices (or other things
+/// that access memory) should store the memory as a GuestAddressSpace<M>.
+/// This example shows that references can also be used as the GuestAddressSpace
+/// implementation, providing a zero-cost abstraction whenever immutable memory
+/// maps are sufficient.
+///
+/// ```
+/// # use std::sync::Arc;
+/// # #[cfg(feature = "backend-mmap")]
+/// # use vm_memory::GuestMemoryMmap;
+/// # use vm_memory::{GuestAddress, GuestMemory, GuestAddressSpace};
+///
+/// pub struct VirtioDevice<AS: GuestAddressSpace> {
+///     mem: Option<AS>,
+/// }
+///
+/// impl<AS: GuestAddressSpace> VirtioDevice<AS> {
+///     fn new() -> Self {
+///         VirtioDevice { mem: None }
+///     }
+///     fn activate(&mut self, mem: AS) {
+///         self.mem = Some(mem)
+///     }
+/// }
+///
+/// # #[cfg(feature = "backend-mmap")]
+/// # fn get_mmap() -> GuestMemoryMmap {
+/// #     GuestMemoryMmap::from_ranges(&[(GuestAddress(0),0)]).unwrap()
+/// # }
+///
+/// # #[cfg(feature = "backend-mmap")]
+/// # fn test_1() {
+/// // Using `VirtioDevice` with an immutable GuestMemoryMmap:
+/// let mut for_immutable_mmap: VirtioDevice<&GuestMemoryMmap> =
+///     VirtioDevice::new();
+/// let mmap = get_mmap();
+/// for_immutable_mmap.activate(&mmap);
+/// let mut another: VirtioDevice<&GuestMemoryMmap> =
+///     VirtioDevice::new();
+/// another.activate(&mmap);
+/// # }
+/// ```
+
+pub trait GuestAddressSpace {
+    /// The type that will be used to access guest memory.
+    type M: GuestMemory;
+
+    /// A type that provides access to the memory.
+    type T: Deref<Target = Self::M>;
+
+    /// Return an object (e.g. a reference or guard) that can be used
+    /// to access memory through this address space.  The object provides
+    /// a consistent snapshot of the memory map.
+    fn memory(&self) -> Self::T;
+}
+
+impl<M: GuestMemory> GuestAddressSpace for &M {
+    type T = Self;
+    type M = M;
+
+    fn memory(&self) -> Self {
+        self
+    }
+}
+
+impl<M: GuestMemory> GuestAddressSpace for Rc<M> {
+    type T = Self;
+    type M = M;
+
+    fn memory(&self) -> Self {
+        self.clone()
+    }
+}
+
+impl<M: GuestMemory> GuestAddressSpace for Arc<M> {
+    type T = Self;
+    type M = M;
+
+    fn memory(&self) -> Self {
+        self.clone()
+    }
+}
+
+/// GuestMemory represents a container for an *immutable* collection of
+/// GuestMemoryRegion objects.  GuestMemory provides the `Bytes<GuestAddress>`
+/// trait to hide the details of accessing guest memory by physical address.
+/// Interior mutability is not allowed for implementations of GuestMemory so
+/// that they always provide a consistent view of the memory map.
 ///
-/// The main responsibilities of the GuestMemory trait are:
-/// - hide the detail of accessing guest's physical address.
+/// The task of the GuestMemory trait are:
 /// - map a request address to a GuestMemoryRegion object and relay the request to it.
 /// - handle cases where an access request spanning two or more GuestMemoryRegion objects.
-///
-/// Note: the regions inside a [`GuestMemory`](trait.GuestMemory.html) object must not overlap.
 pub trait GuestMemory {
     /// Type of objects hosted by the address space.
     type R: GuestMemoryRegion;

src/lib.rs

@@ -30,8 +30,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, GuestMemory, GuestMemoryRegion,
-    GuestUsize, MemoryRegionAddress, Result as GuestMemoryResult,
+    Error as GuestMemoryError, FileOffset, GuestAddress, GuestAddressSpace, GuestMemory,
+    GuestMemoryRegion, GuestUsize, MemoryRegionAddress, Result as GuestMemoryResult,
 };
 
 #[cfg(all(feature = "backend-mmap", unix))]

src/mmap.rs

@@ -518,6 +518,7 @@ mod tests {
     extern crate vmm_sys_util;
 
     use super::*;
+    use crate::GuestAddressSpace;
 
     use std::fs::File;
     use std::mem;
@@ -1093,6 +1094,38 @@ mod tests {
         assert_eq!(gm.clone().regions[1].guest_base, regions[1].0);
     }
 
+    #[test]
+    fn test_memory() {
+        let region_size = 0x400;
+        let regions = vec![
+            (GuestAddress(0x0), region_size),
+            (GuestAddress(0x1000), region_size),
+        ];
+        let mut iterated_regions = Vec::new();
+        let gm = Arc::new(GuestMemoryMmap::from_ranges(&regions).unwrap());
+        let mem = gm.memory();
+
+        let res: guest_memory::Result<()> = mem.with_regions(|_, region| {
+            assert_eq!(region.len(), region_size as GuestUsize);
+            Ok(())
+        });
+        assert!(res.is_ok());
+        let res: guest_memory::Result<()> = mem.with_regions_mut(|_, region| {
+            iterated_regions.push((region.start_addr(), region.len() as usize));
+            Ok(())
+        });
+        assert!(res.is_ok());
+        assert_eq!(regions, iterated_regions);
+
+        assert!(regions
+            .iter()
+            .map(|x| (x.0, x.1))
+            .eq(iterated_regions.iter().map(|x| *x)));
+
+        assert_eq!(gm.clone().regions[0].guest_base, regions[0].0);
+        assert_eq!(gm.clone().regions[1].guest_base, regions[1].0);
+    }
+
     #[test]
     fn test_access_cross_boundary() {
         let f1 = TempFile::new().unwrap().into_file();