GuestRegionMmap

vm_memory::mmap

Struct GuestRegionMmap

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

Available on crate feature backend-mmap only.

Expand description

GuestMemoryRegion implementation that mmaps the guest’s memory region in the current process.

Represents a continuous region of the guest’s physical memory that is backed by a mapping in the virtual address space of the calling process.

Implementations§

impl<B: Bitmap> GuestRegionMmap<B>

pub fn new(mapping: MmapRegion<B>, guest_base: GuestAddress) -> Option<Self>

Create a new memory-mapped memory region for the guest’s physical memory.

Returns None if guest_base + mapping.len() would overflow.

pub fn with_arc( mapping: Arc<MmapRegion<B>>, guest_base: GuestAddress, ) -> Option<Self>

Same as Self::new(), but takes an Arc-wrapped mapping.

pub fn get_mmap(&self) -> Arc<MmapRegion<B>>

Return a clone of the inner Arc<MmapRegion> (as opposed to .deref(), which bypasses the Arc).

The returned reference can be used to construct a new GuestRegionMmap with a different base address (e.g. when switching between memory address spaces based on the guest physical address vs. the VMM userspace virtual address).

impl<B: NewBitmap> GuestRegionMmap<B>

pub fn from_range( addr: GuestAddress, size: usize, file: Option<FileOffset>, ) -> Result<Self, FromRangesError>

Available on crate feature xen only.

Create a new Unix memory-mapped memory region from guest’s physical memory, size and file. This must only be used for tests, doctests, benches and is not designed for end consumers.

Methods from Deref<Target = MmapRegion<B>>§

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

Available on crate feature xen and target_family=unix only.

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

Available on crate feature xen and target_family=unix only.

Returns the size of this region.

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

Available on crate feature xen and target_family=unix only.

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

pub fn prot(&self) -> i32

Available on crate feature xen and target_family=unix only.

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

pub fn flags(&self) -> i32

Available on crate feature xen and target_family=unix only.

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

Available on crate feature xen and target_family=unix only.

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

Available on crate feature xen and target_family=unix only.

Returns true if the region is hugetlbfs

pub fn bitmap(&self) -> &B

Available on crate feature xen and target_family=unix only.

Returns a reference to the inner bitmap object.

pub fn xen_mmap_flags(&self) -> u32

Available on crate feature xen and target_family=unix only.

Returns xen mmap flags.

pub fn xen_mmap_data(&self) -> u32

Available on crate feature xen and target_family=unix only.

Returns xen mmap data.

Trait Implementations§

impl<B: Debug> Debug for GuestRegionMmap<B>

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

Formats the value using the given formatter. Read more

impl<B> Deref for GuestRegionMmap<B>

type Target = MmapRegion<B>

The resulting type after dereferencing.

fn deref(&self) -> &MmapRegion<B>

Dereferences the value.

impl<B: Bitmap> GuestMemoryRegion for GuestRegionMmap<B>

type B = B

Type used for dirty memory tracking.

fn len(&self) -> GuestUsize

Returns the size of the region.

fn start_addr(&self) -> GuestAddress

Returns the minimum (inclusive) address managed by the region.

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

Borrow the associated Bitmap object.

fn get_host_address(&self, addr: MemoryRegionAddress) -> Result<*mut u8>

Returns the host virtual address corresponding to the region address. Read more

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

Returns information regarding the file and offset backing this memory region.

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

Returns a VolatileSlice of count bytes starting at offset.

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

Available on Linux only.

Show if the region is based on the HugeTLBFS. Returns Some(true) if the region is backed by hugetlbfs. None represents that no information is available. Read more

fn last_addr(&self) -> GuestAddress

Returns the maximum (inclusive) address managed by the region.

fn check_address( &self, addr: MemoryRegionAddress, ) -> Option<MemoryRegionAddress>

Returns the given address if it is within this region.

fn address_in_range(&self, addr: MemoryRegionAddress) -> bool

Returns true if the given address is within this region.

fn checked_offset( &self, base: MemoryRegionAddress, offset: usize, ) -> Option<MemoryRegionAddress>

Returns the address plus the offset if it is in this region.

fn to_region_addr(&self, addr: GuestAddress) -> Option<MemoryRegionAddress>

Tries to convert an absolute address to a relative address within this region. Read more

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

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

impl<B: Bitmap> GuestMemoryRegionBytes for GuestRegionMmap<B>

Auto Trait Implementations§

impl<B> Freeze for GuestRegionMmap<B>

impl<B = ()> !RefUnwindSafe for GuestRegionMmap<B>

impl<B> Send for GuestRegionMmap<B>
where B: Sync + Send,

impl<B> Sync for GuestRegionMmap<B>
where B: Sync + Send,

impl<B> Unpin for GuestRegionMmap<B>

impl<B = ()> !UnwindSafe for GuestRegionMmap<B>

Blanket Implementations§

impl<T> Any for T
where T: 'static + ?Sized,

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more

impl<T> Borrow<T> for T
where T: ?Sized,

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more

impl<T> BorrowMut<T> for T
where T: ?Sized,

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more

impl<R> Bytes<MemoryRegionAddress> for R
where R: GuestMemoryRegionBytes,

fn write(&self, buf: &[u8], addr: MemoryRegionAddress) -> Result<usize, Error>

§Examples

Write a slice at guest address 0x1200.

let res = gm
    .write(&[1, 2, 3, 4, 5], GuestAddress(0x1200))
    .expect("Could not write to guest memory");
assert_eq!(5, res);

fn read( &self, buf: &mut [u8], addr: MemoryRegionAddress, ) -> Result<usize, Error>

§Examples

Read a slice of length 16 at guestaddress 0x1200.

let buf = &mut [0u8; 16];
let res = gm
    .read(buf, GuestAddress(0x1200))
    .expect("Could not read from guest memory");
assert_eq!(16, res);

type E = Error

Associated error codes

fn write_slice( &self, buf: &[u8], addr: MemoryRegionAddress, ) -> Result<(), Error>

Writes the entire content of a slice into the container at addr. Read more

fn read_slice( &self, buf: &mut [u8], addr: MemoryRegionAddress, ) -> Result<(), Error>

Reads data from the container at addr to fill an entire slice. Read more

fn read_volatile_from<F>( &self, addr: MemoryRegionAddress, src: &mut F, count: usize, ) -> Result<usize, Error>
where F: ReadVolatile,

Reads up to count bytes from src and writes them into the container at addr. Unlike VolatileRead::read_volatile, this function retries on EINTR being returned from the underlying I/O read operation. Read more

fn read_exact_volatile_from<F>( &self, addr: MemoryRegionAddress, src: &mut F, count: usize, ) -> Result<(), Error>
where F: ReadVolatile,

Reads exactly count bytes from an object and writes them into the container at addr. Read more

fn write_volatile_to<F>( &self, addr: MemoryRegionAddress, dst: &mut F, count: usize, ) -> Result<usize, Error>
where F: WriteVolatile,

Reads up to count bytes from the container at addr and writes them into dst. Unlike VolatileWrite::write_volatile, this function retries on EINTR being returned by the underlying I/O write operation. Read more

fn write_all_volatile_to<F>( &self, addr: MemoryRegionAddress, dst: &mut F, count: usize, ) -> Result<(), Error>
where F: WriteVolatile,

Reads exactly count bytes from the container at addr and writes them into an object. Read more

fn store<T>( &self, val: T, addr: MemoryRegionAddress, order: Ordering, ) -> Result<(), Error>
where T: AtomicAccess,

Atomically store a value at the specified address.

fn load<T>( &self, addr: MemoryRegionAddress, order: Ordering, ) -> Result<T, Error>
where T: AtomicAccess,

Atomically load a value from the specified address.

fn write_obj<T: ByteValued>(&self, val: T, addr: A) -> Result<(), Self::E>

Writes an object into the container at addr. Read more

fn read_obj<T: ByteValued>(&self, addr: A) -> Result<T, Self::E>

Reads an object from the container at addr. Read more

impl<T> From<T> for T

fn from(t: T) -> T

Returns the argument unchanged.

impl<T, U> Into<U> for T
where U: From<T>,

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

impl<P, T> Receiver for P
where P: Deref<Target = T> + ?Sized, T: ?Sized,

type Target = T

🔬This is a nightly-only experimental API. (arbitrary_self_types)

The target type on which the method may be called.

impl<T, U> TryFrom<U> for T
where U: Into<T>,

type Error = Infallible

The type returned in the event of a conversion error.

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.