Add "get_slice" and "as_volatile_slice" methods to GuestMemoryRegion.

Fixes #76.

"get_slice" and "as_volatile_slice" provide better way to access
guest memory than "get_host_address" does.

They both build ranged-checked "VolatileSlice". Difference is, "get_
slice" takes "offset" and "size" parameters, while "as_volatile_
slice" makes slice for the whole region.

Signed-off-by: Michael Zhao <michael.zhao@arm.com>

Author: michael2012z

coverage_config.json

@@ -1,5 +1,5 @@
 {
-  "coverage_score": 84.8,
+  "coverage_score": 85.6,
   "exclude_path": "mmap_windows.rs",
   "crate_features": "backend-mmap,backend-atomic"
 }

src/guest_memory.rs

@@ -246,6 +246,45 @@ pub trait GuestMemoryRegion: Bytes<MemoryRegionAddress, E = Error> {
     unsafe fn as_mut_slice(&self) -> Option<&mut [u8]> {
         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<volatile_memory::VolatileSlice> {
+        Err(Error::HostAddressNotAvailable)
+    }
+
+    /// Gets a slice of memory for the entire region that supports volatile access.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # #[cfg(feature = "backend-mmap")]
+    /// # use vm_memory::{GuestAddress, MmapRegion, GuestRegionMmap, GuestMemoryRegion};
+    /// # #[cfg(feature = "backend-mmap")]
+    /// # use vm_memory::volatile_memory::{VolatileMemory, VolatileSlice, VolatileRef};
+    ///
+    /// # #[cfg(feature = "backend-mmap")]
+    /// # fn test_as_volatile_slice() {
+    ///     let region =
+    ///         GuestRegionMmap::new(MmapRegion::new(0x400).unwrap(), GuestAddress(0x0))
+    ///         .unwrap();
+    ///     let slice = region.as_volatile_slice().unwrap();
+    ///     let v = 42u32;
+    ///     let r = slice.get_ref::<u32>(0x200).unwrap();
+    ///     r.store(v);
+    ///     assert_eq!(r.load(), v);
+    /// # }
+    /// # #[cfg(feature = "backend-mmap")]
+    /// # test_as_volatile_slice();
+    /// ```
+    fn as_volatile_slice(&self) -> Result<volatile_memory::VolatileSlice> {
+        self.get_slice(MemoryRegionAddress(0), self.len() as usize)
+    }
 }
 
 /// GuestAddressSpace provides a way to retrieve a GuestMemory object.
@@ -563,6 +602,18 @@ pub trait GuestMemory {
             .ok_or_else(|| Error::InvalidGuestAddress(addr))
             .and_then(|(r, addr)| r.get_host_address(addr))
     }
+
+    /// Returns a [`VolatileSlice`](struct.VolatileSlice.html) of `count` bytes starting at
+    /// `addr`.
+    fn get_slice(
+        &self,
+        addr: GuestAddress,
+        count: usize,
+    ) -> Result<volatile_memory::VolatileSlice> {
+        self.to_region_addr(addr)
+            .ok_or_else(|| Error::InvalidGuestAddress(addr))
+            .and_then(|(r, addr)| r.get_slice(addr, count))
+    }
 }
 
 impl<T: GuestMemory> Bytes<GuestAddress> for T {

src/mmap.rs

@@ -24,7 +24,7 @@ use crate::address::Address;
 use crate::guest_memory::{
     self, FileOffset, GuestAddress, GuestMemory, GuestMemoryRegion, GuestUsize, MemoryRegionAddress,
 };
-use crate::volatile_memory::VolatileMemory;
+use crate::volatile_memory::{VolatileMemory, VolatileSlice};
 use crate::Bytes;
 
 #[cfg(unix)]
@@ -165,6 +165,7 @@ impl Bytes<MemoryRegionAddress> for GuestRegionMmap {
     fn write(&self, buf: &[u8], addr: MemoryRegionAddress) -> guest_memory::Result<usize> {
         let maddr = addr.raw_value() as usize;
         self.as_volatile_slice()
+            .unwrap()
             .write(buf, maddr)
             .map_err(Into::into)
     }
@@ -183,20 +184,23 @@ impl Bytes<MemoryRegionAddress> for GuestRegionMmap {
     fn read(&self, buf: &mut [u8], addr: MemoryRegionAddress) -> guest_memory::Result<usize> {
         let maddr = addr.raw_value() as usize;
         self.as_volatile_slice()
+            .unwrap()
             .read(buf, maddr)
             .map_err(Into::into)
     }
 
     fn write_slice(&self, buf: &[u8], addr: MemoryRegionAddress) -> guest_memory::Result<()> {
         let maddr = addr.raw_value() as usize;
         self.as_volatile_slice()
+            .unwrap()
             .write_slice(buf, maddr)
             .map_err(Into::into)
     }
 
     fn read_slice(&self, buf: &mut [u8], addr: MemoryRegionAddress) -> guest_memory::Result<()> {
         let maddr = addr.raw_value() as usize;
         self.as_volatile_slice()
+            .unwrap()
             .read_slice(buf, maddr)
             .map_err(Into::into)
     }
@@ -232,6 +236,7 @@ impl Bytes<MemoryRegionAddress> for GuestRegionMmap {
     {
         let maddr = addr.raw_value() as usize;
         self.as_volatile_slice()
+            .unwrap()
             .read_from::<F>(maddr, src, count)
             .map_err(Into::into)
     }
@@ -267,6 +272,7 @@ impl Bytes<MemoryRegionAddress> for GuestRegionMmap {
     {
         let maddr = addr.raw_value() as usize;
         self.as_volatile_slice()
+            .unwrap()
             .read_exact_from::<F>(maddr, src, count)
             .map_err(Into::into)
     }
@@ -299,6 +305,7 @@ impl Bytes<MemoryRegionAddress> for GuestRegionMmap {
     {
         let maddr = addr.raw_value() as usize;
         self.as_volatile_slice()
+            .unwrap()
             .write_to::<F>(maddr, dst, count)
             .map_err(Into::into)
     }
@@ -331,6 +338,7 @@ impl Bytes<MemoryRegionAddress> for GuestRegionMmap {
     {
         let maddr = addr.raw_value() as usize;
         self.as_volatile_slice()
+            .unwrap()
             .write_all_to::<F>(maddr, dst, count)
             .map_err(Into::into)
     }
@@ -364,6 +372,15 @@ impl GuestMemoryRegion for GuestRegionMmap {
             .ok_or(guest_memory::Error::InvalidBackendAddress)
             .map(|addr| self.as_ptr().wrapping_offset(addr.raw_value() as isize))
     }
+
+    fn get_slice(
+        &self,
+        offset: MemoryRegionAddress,
+        count: usize,
+    ) -> guest_memory::Result<VolatileSlice> {
+        let slice = self.mapping.get_slice(offset.raw_value() as usize, count)?;
+        Ok(slice)
+    }
 }
 
 /// [`GuestMemory`](trait.GuestMemory.html) implementation that mmaps the guest's memory
@@ -972,7 +989,8 @@ mod tests {
             let slice = guest_mem
                 .find_region(GuestAddress(0))
                 .unwrap()
-                .as_volatile_slice();
+                .as_volatile_slice()
+                .unwrap();
 
             let buf = &mut [0, 0, 0, 0, 0];
             assert_eq!(slice.read(buf, 0).unwrap(), 5);
@@ -1301,4 +1319,79 @@ mod tests {
         assert_eq!(gm.regions[0].start_addr(), GuestAddress(0x0000));
         assert_eq!(region.start_addr(), GuestAddress(0x10_0000));
     }
+
+    #[test]
+    fn test_guest_memory_mmap_get_slice() {
+        let region_addr = GuestAddress(0);
+        let region_size = 0x400;
+        let region =
+            GuestRegionMmap::new(MmapRegion::new(region_size).unwrap(), region_addr).unwrap();
+
+        // Normal case.
+        let slice_addr = MemoryRegionAddress(0x100);
+        let slice_size = 0x200;
+        let slice = region.get_slice(slice_addr, slice_size).unwrap();
+        assert_eq!(slice.len(), slice_size);
+
+        // Empty slice.
+        let slice_addr = MemoryRegionAddress(0x200);
+        let slice_size = 0x0;
+        let slice = region.get_slice(slice_addr, slice_size).unwrap();
+        assert!(slice.is_empty());
+
+        // Error case when slice_size is beyond the boundary.
+        let slice_addr = MemoryRegionAddress(0x300);
+        let slice_size = 0x200;
+        assert!(region.get_slice(slice_addr, slice_size).is_err());
+    }
+
+    #[test]
+    fn test_guest_memory_mmap_as_volatile_slice() {
+        let region_addr = GuestAddress(0);
+        let region_size = 0x400;
+        let region =
+            GuestRegionMmap::new(MmapRegion::new(region_size).unwrap(), region_addr).unwrap();
+
+        // Test slice length.
+        let slice = region.as_volatile_slice().unwrap();
+        assert_eq!(slice.len(), region_size);
+
+        // Test slice data.
+        let v = 0x1234_5678u32;
+        let r = slice.get_ref::<u32>(0x200).unwrap();
+        r.store(v);
+        assert_eq!(r.load(), v);
+    }
+
+    #[test]
+    fn test_guest_memory_get_slice() {
+        let start_addr1 = GuestAddress(0);
+        let start_addr2 = GuestAddress(0x800);
+        let guest_mem =
+            GuestMemoryMmap::from_ranges(&[(start_addr1, 0x400), (start_addr2, 0x400)]).unwrap();
+
+        // Normal cases.
+        let slice_size = 0x200;
+        let slice = guest_mem
+            .get_slice(GuestAddress(0x100), slice_size)
+            .unwrap();
+        assert_eq!(slice.len(), slice_size);
+
+        let slice_size = 0x400;
+        let slice = guest_mem
+            .get_slice(GuestAddress(0x800), slice_size)
+            .unwrap();
+        assert_eq!(slice.len(), slice_size);
+
+        // Empty slice.
+        assert!(guest_mem
+            .get_slice(GuestAddress(0x900), 0)
+            .unwrap()
+            .is_empty());
+
+        // Error cases, wrong size or base address.
+        assert!(guest_mem.get_slice(GuestAddress(0), 0x500).is_err());
+        assert!(guest_mem.get_slice(GuestAddress(0x600), 0x100).is_err());
+        assert!(guest_mem.get_slice(GuestAddress(0xc00), 0x100).is_err());
+    }
 }