Trait vm_memory::guest_memory::GuestMemoryRegion

pub trait GuestMemoryRegion: Bytes<MemoryRegionAddress, E = Error> {
    type B: Bitmap;

    // Required methods
    fn len(&self) -> GuestUsize;
    fn start_addr(&self) -> GuestAddress;
    fn bitmap(&self) -> &Self::B;

    // Provided methods
    fn last_addr(&self) -> GuestAddress { ... }
    fn check_address(
        &self,
        addr: MemoryRegionAddress
    ) -> Option<MemoryRegionAddress> { ... }
    fn address_in_range(&self, addr: MemoryRegionAddress) -> bool { ... }
    fn checked_offset(
        &self,
        base: MemoryRegionAddress,
        offset: usize
    ) -> Option<MemoryRegionAddress> { ... }
    fn to_region_addr(&self, addr: GuestAddress) -> Option<MemoryRegionAddress> { ... }
    fn get_host_address(&self, _addr: MemoryRegionAddress) -> Result<*mut u8> { ... }
    fn file_offset(&self) -> Option<&FileOffset> { ... }
    unsafe fn as_slice(&self) -> Option<&[u8]> { ... }
    unsafe fn as_mut_slice(&self) -> Option<&mut [u8]> { ... }
    fn get_slice(
        &self,
        offset: MemoryRegionAddress,
        count: usize
    ) -> Result<VolatileSlice<'_, BS<'_, Self::B>>> { ... }
    fn as_volatile_slice(&self) -> Result<VolatileSlice<'_, BS<'_, Self::B>>> { ... }
    fn is_hugetlbfs(&self) -> Option<bool> { ... }
}

Represents a continuous region of guest physical memory.

Required Associated Types

type B: Bitmap

Type used for dirty memory tracking.

Required Methods

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.

Provided Methods

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.

Returns None if addr is out of the bounds of this region.

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

Returns the host virtual address corresponding to the region address.

Some GuestMemory implementations, like GuestMemoryMmap, have the capability to mmap guest address range into host virtual address space for direct access, so the corresponding host virtual address may be passed to other subsystems.

Note

The underlying guest memory is not protected from memory aliasing, which breaks the Rust memory safety model. It’s the caller’s responsibility to ensure that there’s no concurrent accesses to the underlying guest memory.

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

Returns information regarding the file and offset backing this memory 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.

Returns None if the region does not support slice-based access.

Safety

Unsafe because of possible aliasing.

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.

Returns None if the region does not support slice-based access.

Safety

Unsafe because of possible aliasing. Mutable accesses performed through the returned slice are not visible to the dirty bitmap tracking functionality of the region, and must be manually recorded using the associated bitmap object.

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

Returns a VolatileSlice of count bytes starting at offset.

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

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

Examples (uses the backend-mmap feature)

let region = GuestRegionMmap::<()>::from_range(GuestAddress(0x0), 0x400, None)
    .expect("Could not create guest memory");
let slice = region
    .as_volatile_slice()
    .expect("Could not get volatile slice");

let v = 42u32;
let r = slice
    .get_ref::<u32>(0x200)
    .expect("Could not get reference");
r.store(v);
assert_eq!(r.load(), v);

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

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.

Examples (uses the backend-mmap feature)

let addr = GuestAddress(0x1000);
let mem = GuestMemoryMmap::<()>::from_ranges(&[(addr, 0x1000)]).unwrap();
let r = mem.find_region(addr).unwrap();
assert_eq!(r.is_hugetlbfs(), None);

Object Safety

This trait is not object safe.

Implementors

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

type B = B