Struct GuestRegionMmap

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

Available on crate feature backend-mmap only.

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, ) -> Result<Self, Error>

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

impl<B: NewBitmap> GuestRegionMmap<B>

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

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 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 Unix only.

Returns the size of this region.

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

Available on crate feature xen and 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 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 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 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 Unix only.

Returns true if the region is hugetlbfs

pub fn bitmap(&self) -> &B

Available on crate feature xen and Unix only.

Returns a reference to the inner bitmap object.

pub fn xen_mmap_flags(&self) -> u32

Available on crate feature xen and Unix only.

Returns xen mmap flags.

pub fn xen_mmap_data(&self) -> u32

Available on crate feature xen and Unix only.

Returns xen mmap data.

Trait Implementations

impl<B: Bitmap> Bytes<MemoryRegionAddress> for GuestRegionMmap<B>

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

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>

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);

fn read_from<F>( &self, addr: MemoryRegionAddress, src: &mut F, count: usize, ) -> Result<usize>

where F: Read,

👎Deprecated: Use .read_volatile_from or the functions of the ReadVolatile trait instead

Examples

• Read bytes from /dev/urandom

let mut file = File::open(Path::new("/dev/urandom")).expect("Could not open /dev/urandom");

gm.read_from(addr, &mut file, 128)
    .expect("Could not read from /dev/urandom into guest memory");

let read_addr = addr.checked_add(8).expect("Could not compute read address");
let rand_val: u32 = gm
    .read_obj(read_addr)
    .expect("Could not read u32 val from /dev/urandom");

fn read_exact_from<F>( &self, addr: MemoryRegionAddress, src: &mut F, count: usize, ) -> Result<()>

where F: Read,

👎Deprecated: Use .read_exact_volatile_from or the functions of the ReadVolatile trait instead

Examples

• Read bytes from /dev/urandom

let mut file = File::open(Path::new("/dev/urandom")).expect("Could not open /dev/urandom");

gm.read_exact_from(addr, &mut file, 128)
    .expect("Could not read from /dev/urandom into guest memory");

let read_addr = addr.checked_add(8).expect("Could not compute read address");
let rand_val: u32 = gm
    .read_obj(read_addr)
    .expect("Could not read u32 val from /dev/urandom");

fn write_to<F>( &self, addr: MemoryRegionAddress, dst: &mut F, count: usize, ) -> Result<usize>

where F: Write,

👎Deprecated: Use .write_volatile_to or the functions of the WriteVolatile trait instead

Writes data from the region to a writable object.

Examples

• Write 128 bytes to a /dev/null file

let mut file = OpenOptions::new()
    .write(true)
    .open("/dev/null")
    .expect("Could not open /dev/null");

gm.write_to(start_addr, &mut file, 128)
    .expect("Could not write to file from guest memory");

fn write_all_to<F>( &self, addr: MemoryRegionAddress, dst: &mut F, count: usize, ) -> Result<()>

where F: Write,

👎Deprecated: Use .write_all_volatile_to or the functions of the WriteVolatile trait instead

Writes data from the region to a writable object.

Examples

• Write 128 bytes to a /dev/null file

let mut file = OpenOptions::new()
    .write(true)
    .open("/dev/null")
    .expect("Could not open /dev/null");

gm.write_all_to(start_addr, &mut file, 128)
    .expect("Could not write to file from guest memory");

type E = Error

Associated error codes

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

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

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

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

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

Atomically store a value at the specified address.

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

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.

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

Reads an object from the container at addr.

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

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

Formats the value using the given formatter.

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) -> &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.

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.

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.

unsafe fn as_slice(&self) -> Option<&[u8]>

👎Deprecated: It is impossible to use this function for accessing memory of a running virtual machine without violating aliasing rules

Returns a slice corresponding to the data in the region.

unsafe fn as_mut_slice(&self) -> Option<&mut [u8]>

👎Deprecated: It is impossible to use this function for accessing memory of a running virtual machine without violating aliasing rules

Returns a mutable slice corresponding to the data in the region.

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

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