Struct MmapRegion

pub struct MmapRegion<B = ()> { /* private fields */ }

Available on crate feature backend-mmap and crate feature xen and Unix only.

Helper structure for working with mmaped memory regions with Xen.

The structure is used for accessing the guest’s physical memory by mmapping it into the current process.

Limitations

When running a 64-bit virtual machine on a 32-bit hypervisor, only part of the guest’s physical memory may be mapped into the current process due to the limited virtual address space size of the process.

Implementations

impl<B: NewBitmap> MmapRegion<B>

pub fn from_range(range: MmapRange) -> Result<Self, Error>

Creates a shared anonymous mapping of size bytes.

Arguments

• range - An instance of type MmapRange.

Examples

• Write a slice at guest address 0x1200 with Xen’s Grant mapping.

use std::fs::File;
use std::path::Path;
use vm_memory::{
    Bytes, FileOffset, GuestAddress, GuestMemoryMmap, GuestRegionMmap, MmapRange, MmapRegion,
    MmapXenFlags,
};

let addr = GuestAddress(0x1000);
let file = Some(FileOffset::new(
    File::open(Path::new("/dev/xen/gntdev")).expect("Could not open file"),
    0,
));

let range = MmapRange::new(0x400, file, addr, MmapXenFlags::GRANT.bits(), 0);

let r = GuestRegionMmap::new(
    MmapRegion::<()>::from_range(range).expect("Could not create mmap region"),
    addr,
)
.expect("Could not create guest region");

let mut gm = GuestMemoryMmap::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");
assert_eq!(5, res);

• Write a slice at guest address 0x1200 with Xen’s Foreign mapping.

use std::fs::File;
use std::path::Path;
use vm_memory::{
    Bytes, FileOffset, GuestAddress, GuestMemoryMmap, GuestRegionMmap, MmapRange, MmapRegion,
    MmapXenFlags,
};

let addr = GuestAddress(0x1000);
let file = Some(FileOffset::new(
    File::open(Path::new("/dev/xen/privcmd")).expect("Could not open file"),
    0,
));

let range = MmapRange::new(0x400, file, addr, MmapXenFlags::FOREIGN.bits(), 0);

let r = GuestRegionMmap::new(
    MmapRegion::<()>::from_range(range).expect("Could not create mmap region"),
    addr,
)
.expect("Could not create guest region");

let mut gm = GuestMemoryMmap::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");
assert_eq!(5, res);

impl<B: Bitmap> MmapRegion<B>

pub fn as_ptr(&self) -> *mut u8

Returns a pointer to the beginning of the memory region. Mutable accesses performed using the resulting pointer are not automatically accounted for by the dirty bitmap tracking functionality.

Should only be used for passing this region to ioctls for setting guest memory.

pub fn size(&self) -> usize

Returns the size of this region.

pub fn file_offset(&self) -> Option<&FileOffset>

Returns information regarding the offset into the file backing this region (if any).

pub fn prot(&self) -> i32

Returns the value of the prot parameter passed to mmap when mapping this region.

pub fn flags(&self) -> i32

Returns the value of the flags parameter passed to mmap when mapping this region.

pub fn fds_overlap<T: Bitmap>(&self, other: &MmapRegion<T>) -> bool

Checks whether this region and other are backed by overlapping FileOffset objects.

This is mostly a sanity check available for convenience, as different file descriptors can alias the same file.

pub fn set_hugetlbfs(&mut self, hugetlbfs: bool)

Set the hugetlbfs of the region

pub fn is_hugetlbfs(&self) -> Option<bool>

Returns true if the region is hugetlbfs

pub fn bitmap(&self) -> &B

Returns a reference to the inner bitmap object.

pub fn xen_mmap_flags(&self) -> u32

Returns xen mmap flags.

pub fn xen_mmap_data(&self) -> u32

Returns xen mmap data.

Trait Implementations

impl<B: Debug> Debug for MmapRegion<B>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<B: Bitmap> VolatileMemory for MmapRegion<B>

type B = B

Type used for dirty memory tracking.

fn len(&self) -> usize

Gets the size of this slice.

fn get_slice( &self, offset: usize, count: usize, ) -> Result<VolatileSlice<'_, BS<'_, B>>>

Returns a VolatileSlice of count bytes starting at offset.

fn is_empty(&self) -> bool

Check whether the region is empty.

fn as_volatile_slice(&self) -> VolatileSlice<'_, BS<'_, Self::B>>

Gets a slice of memory for the entire region that supports volatile access.

fn get_ref<T: ByteValued>( &self, offset: usize, ) -> Result<VolatileRef<'_, T, BS<'_, Self::B>>>

Gets a VolatileRef at offset.

fn get_array_ref<T: ByteValued>( &self, offset: usize, n: usize, ) -> Result<VolatileArrayRef<'_, T, BS<'_, Self::B>>>

Returns a VolatileArrayRef of n elements starting at offset.

unsafe fn aligned_as_ref<T: ByteValued>(&self, offset: usize) -> Result<&T>

Returns a reference to an instance of T at offset.

unsafe fn aligned_as_mut<T: ByteValued>(&self, offset: usize) -> Result<&mut T>

Returns a mutable reference to an instance of T at offset. Mutable accesses performed using the resulting reference are not automatically accounted for by the dirty bitmap tracking functionality.

fn get_atomic_ref<T: AtomicInteger>(&self, offset: usize) -> Result<&T>

Returns a reference to an instance of T at offset. Mutable accesses performed using the resulting reference are not automatically accounted for by the dirty bitmap tracking functionality.

fn compute_end_offset(&self, base: usize, offset: usize) -> Result<usize>

Returns the sum of base and offset if the resulting address is valid.

impl<B: Send> Send for MmapRegion<B>

impl<B: Sync> Sync for MmapRegion<B>