xen: Introduce GuestMemoryXen and use it in doc tests

This is a xen specific version of `GuestMemoryMmap`. This makes the xen
module independent of the cfg'd types in mmap.rs, meaning we are almost
ready to allow enabling both Mmap and Xen support at the same time.

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

Author: roypat

src/lib.rs

@@ -67,7 +67,7 @@ pub use mmap::{GuestMemoryMmap, GuestRegionMmap, MmapRegion};
 pub use mmap::{MmapRange, MmapXenFlags};
 
 #[cfg(all(feature = "xen", unix))]
-pub use mmap::xen::MmapRegion as MmapRegionXen;
+pub use mmap::xen::{GuestMemoryXen, MmapRegion as MmapRegionXen};
 
 pub mod volatile_memory;
 pub use volatile_memory::{

src/mmap/xen.rs

@@ -28,8 +28,8 @@ use crate::bitmap::{Bitmap, NewBitmap, BS};
 use crate::guest_memory::{FileOffset, GuestAddress};
 use crate::volatile_memory::{self, VolatileMemory, VolatileSlice};
 use crate::{
-    guest_memory, Address, GuestMemoryRegion, GuestMemoryRegionBytes, GuestUsize,
-    MemoryRegionAddress,
+    guest_memory, Address, GuestMemoryRegion, GuestMemoryRegionBytes, GuestRegionCollection,
+    GuestUsize, MemoryRegionAddress,
 };
 
 /// Error conditions that may arise when creating a new `MmapRegion` object.
@@ -199,6 +199,12 @@ impl<B: Bitmap> GuestMemoryRegion for MmapRegion<B> {
 
 impl<B: Bitmap> GuestMemoryRegionBytes for MmapRegion<B> {}
 
+/// A collection of Xen guest memory regions.
+///
+/// Represents the entire physical memory of the guest by tracking all its memory regions.
+/// Each region is an instance of [`MmapRegionXen`].
+pub type GuestMemoryXen<B> = GuestRegionCollection<MmapRegion<B>>;
+
 // SAFETY: Send and Sync aren't automatically inherited for the raw address pointer.
 // Accessing that pointer is only done through the stateless interface which
 // allows the object to be shared by multiple threads without a decrease in
@@ -220,8 +226,7 @@ impl<B: NewBitmap> MmapRegion<B> {
     /// use std::fs::File;
     /// use std::path::Path;
     /// use vm_memory::{
-    ///     Bytes, FileOffset, GuestAddress, GuestMemoryMmap, GuestRegionMmap, MmapRange, MmapRegion,
-    ///     MmapXenFlags,
+    ///     Bytes, FileOffset, GuestAddress, GuestMemoryXen, MmapRange, MmapRegionXen, MmapXenFlags,
     /// };
     /// # use vmm_sys_util::tempfile::TempFile;
     ///
@@ -237,13 +242,9 @@ impl<B: NewBitmap> MmapRegion<B> {
     /// # // We need a UNIX mapping for tests to succeed.
     /// # let range = MmapRange::new_unix(0x400, None, addr);
     ///
-    /// let r = GuestRegionMmap::new(
-    ///     MmapRegion::<()>::from_range(range).expect("Could not create mmap region"),
-    ///     addr,
-    /// )
-    /// .expect("Could not create guest region");
+    /// let r = MmapRegionXen::<()>::from_range(range).expect("Could not create mmap region");
     ///
-    /// let mut gm = GuestMemoryMmap::from_regions(vec![r]).expect("Could not create guest memory");
+    /// let mut gm = GuestMemoryXen::from_regions(vec![r]).expect("Could not create guest memory");
     /// let res = gm
     ///     .write(&[1, 2, 3, 4, 5], GuestAddress(0x1200))
     ///     .expect("Could not write to guest memory");
@@ -256,8 +257,7 @@ impl<B: NewBitmap> MmapRegion<B> {
     /// use std::fs::File;
     /// use std::path::Path;
     /// use vm_memory::{
-    ///     Bytes, FileOffset, GuestAddress, GuestMemoryMmap, GuestRegionMmap, MmapRange, MmapRegion,
-    ///     MmapXenFlags,
+    ///     Bytes, FileOffset, GuestAddress, GuestMemoryXen, MmapRange, MmapRegionXen, MmapXenFlags,
     /// };
     /// # use vmm_sys_util::tempfile::TempFile;
     ///
@@ -273,13 +273,9 @@ impl<B: NewBitmap> MmapRegion<B> {
     /// # // We need a UNIX mapping for tests to succeed.
     /// # let range = MmapRange::new_unix(0x400, None, addr);
     ///
-    /// let r = GuestRegionMmap::new(
-    ///     MmapRegion::<()>::from_range(range).expect("Could not create mmap region"),
-    ///     addr,
-    /// )
-    /// .expect("Could not create guest region");
+    /// let r = MmapRegionXen::<()>::from_range(range).expect("Could not create mmap region");
     ///
-    /// let mut gm = GuestMemoryMmap::from_regions(vec![r]).expect("Could not create guest memory");
+    /// let mut gm = GuestMemoryXen::from_regions(vec![r]).expect("Could not create guest memory");
     /// let res = gm
     ///     .write(&[1, 2, 3, 4, 5], GuestAddress(0x1200))
     ///     .expect("Could not write to guest memory");