Struct vm_memory::MmapRegion

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

Helper structure for working with mmaped memory regions in Unix.

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 new(size: usize) -> Result<Self, Error>

Creates a shared anonymous mapping of size bytes.

Arguments

• size - The size of the memory region in bytes.

pub fn from_file(file_offset: FileOffset, size: usize) -> Result<Self, Error>

Creates a shared file mapping of size bytes.

Arguments

• file_offset - The mapping will be created at offset file_offset.start in the file referred to by file_offset.file.
• size - The size of the memory region in bytes.

pub fn build(
    file_offset: Option<FileOffset>,
    size: usize,
    prot: i32,
    flags: i32
) -> Result<Self, Error>

Creates a mapping based on the provided arguments.

Arguments

• file_offset - if provided, the method will create a file mapping at offset file_offset.start in the file referred to by file_offset.file.
• size - The size of the memory region in bytes.
• prot - The desired memory protection of the mapping.
• flags - This argument determines whether updates to the mapping are visible to other processes mapping the same region, and whether updates are carried through to the underlying file.

pub unsafe fn build_raw(
    addr: *mut u8,
    size: usize,
    prot: i32,
    flags: i32
) -> Result<Self, Error>

Creates a MmapRegion instance for an externally managed mapping.

This method is intended to be used exclusively in situations in which the mapping backing the region is provided by an entity outside the control of the caller (e.g. the dynamic linker).

Arguments

• addr - Pointer to the start of the mapping. Must be page-aligned.
• size - The size of the memory region in bytes.
• prot - Must correspond to the memory protection attributes of the existing mapping.
• flags - Must correspond to the flags that were passed to mmap for the creation of the existing mapping.

Safety

To use this safely, the caller must guarantee that addr and size define a region within a valid mapping that is already present in the process.

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 owned(&self) -> bool

Returns true if the mapping is owned by this MmapRegion instance.

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.

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> Drop for MmapRegion<B>

fn drop(&mut self)

Executes the destructor for this type.

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>