Trait GuestMemoryRegion 

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

    // Required methods
    fn len(&self) -> <GuestAddress as AddressValue>::V;
    fn start_addr(&self) -> GuestAddress;
    fn bitmap(&self) -> <Self::B as WithBitmapSlice<'_>>::S;

    // 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, Error> { ... }
    fn file_offset(&self) -> Option<&FileOffset> { ... }
    fn get_slice(
        &self,
        offset: MemoryRegionAddress,
        count: usize,
    ) -> Result<VolatileSlice<'_, <Self::B as WithBitmapSlice<'_>>::S>, Error> { ... }
    fn as_volatile_slice(
        &self,
    ) -> Result<VolatileSlice<'_, <Self::B as WithBitmapSlice<'_>>::S>, Error> { ... }
    fn is_hugetlbfs(&self) -> Option<bool> { ... }
}

Represents a continuous region of guest physical memory.

Note that the Bytes super trait requirement can be satisfied by implementing GuestMemoryRegionBytes, which provides a default implementation of Bytes for memory regions that are backed by physical RAM:

///
use vm_memory::bitmap::BS;
use vm_memory::{GuestAddress, GuestMemoryRegion, GuestMemoryRegionBytes, GuestUsize};

struct MyRegion;

impl GuestMemoryRegion for MyRegion {
    type B = ();
    fn len(&self) -> GuestUsize {
        todo!()
    }
    fn start_addr(&self) -> GuestAddress {
        todo!()
    }
    fn bitmap(&self) {
        todo!()
    }
}

impl GuestMemoryRegionBytes for MyRegion {}

Required Associated Types

type B: Bitmap

Type used for dirty memory tracking.

Required Methods

fn len(&self) -> <GuestAddress as AddressValue>::V

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 as WithBitmapSlice<'_>>::S

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, Error>

Returns the host virtual address corresponding to the region address.

Some GuestMemoryBackend 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.

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

Returns a VolatileSlice of count bytes starting at offset.

fn as_volatile_slice( &self, ) -> Result<VolatileSlice<'_, <Self::B as WithBitmapSlice<'_>>::S>, Error>

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>

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.

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

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<B> GuestMemoryRegion for GuestRegionMmap<B>

where B: Bitmap,

type B = B