Trait GuestMemory 

pub trait GuestMemory {
    type R: GuestMemoryRegion;

    // Required method
    fn iter(&self) -> impl Iterator<Item = &Self::R>;

    // Provided methods
    fn num_regions(&self) -> usize { ... }
    fn find_region(&self, addr: GuestAddress) -> Option<&Self::R> { ... }
    fn last_addr(&self) -> GuestAddress { ... }
    fn to_region_addr(
        &self,
        addr: GuestAddress,
    ) -> Option<(&Self::R, MemoryRegionAddress)> { ... }
    fn address_in_range(&self, addr: GuestAddress) -> bool { ... }
    fn check_address(&self, addr: GuestAddress) -> Option<GuestAddress> { ... }
    fn check_range(&self, base: GuestAddress, len: usize) -> bool { ... }
    fn checked_offset(
        &self,
        base: GuestAddress,
        offset: usize,
    ) -> Option<GuestAddress> { ... }
    fn try_access<F>(
        &self,
        count: usize,
        addr: GuestAddress,
        f: F,
    ) -> Result<usize, Error>
       where F: FnMut(usize, usize, MemoryRegionAddress, &Self::R) -> Result<usize, Error> { ... }
    fn get_host_address(&self, addr: GuestAddress) -> Result<*mut u8, Error> { ... }
    fn get_slice(
        &self,
        addr: GuestAddress,
        count: usize,
    ) -> Result<VolatileSlice<'_, <<Self::R as GuestMemoryRegion>::B as WithBitmapSlice<'_>>::S>, Error> { ... }
    fn get_slices<'a>(
        &'a self,
        addr: GuestAddress,
        count: usize,
    ) -> GuestMemorySliceIterator<'a, Self> { ... }
}

GuestMemory represents a container for an immutable collection of GuestMemoryRegion objects. GuestMemory provides the Bytes<GuestAddress> trait to hide the details of accessing guest memory by physical address. Interior mutability is not allowed for implementations of GuestMemory so that they always provide a consistent view of the memory map.

The task of the GuestMemory trait are:

• map a request address to a GuestMemoryRegion object and relay the request to it.
• handle cases where an access request spanning two or more GuestMemoryRegion objects.

Required Associated Types

type R: GuestMemoryRegion

Type of objects hosted by the address space.

Required Methods

fn iter(&self) -> impl Iterator<Item = &Self::R>

Gets an iterator over the entries in the collection.

Examples

• Compute the total size of all memory mappings in KB by iterating over the memory regions and dividing their sizes to 1024, then summing up the values in an accumulator. (uses the backend-mmap feature)

let start_addr1 = GuestAddress(0x0);
let start_addr2 = GuestAddress(0x400);
let gm = GuestMemoryMmap::<()>::from_ranges(&vec![(start_addr1, 1024), (start_addr2, 2048)])
    .expect("Could not create guest memory");

let total_size = gm
    .iter()
    .map(|region| region.len() / 1024)
    .fold(0, |acc, size| acc + size);
assert_eq!(3, total_size)

Provided Methods

fn num_regions(&self) -> usize

Returns the number of regions in the collection.

fn find_region(&self, addr: GuestAddress) -> Option<&Self::R>

Returns the region containing the specified address or None.

fn last_addr(&self) -> GuestAddress

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

Examples (uses the backend-mmap feature)

let start_addr = GuestAddress(0x1000);
let mut gm = GuestMemoryMmap::<()>::from_ranges(&vec![(start_addr, 0x400)])
    .expect("Could not create guest memory");

assert_eq!(start_addr.checked_add(0x3ff), Some(gm.last_addr()));

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

Tries to convert an absolute address to a relative address within the corresponding region.

Returns None if addr isn’t present within the memory of the guest.

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

Returns true if the given address is present within the memory of the guest.

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

Returns the given address if it is present within the memory of the guest.

fn check_range(&self, base: GuestAddress, len: usize) -> bool

Check whether the range [base, base + len) is valid.

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

Returns the address plus the offset if it is present within the memory of the guest.

fn try_access<F>( &self, count: usize, addr: GuestAddress, f: F, ) -> Result<usize, Error>

where F: FnMut(usize, usize, MemoryRegionAddress, &Self::R) -> Result<usize, Error>,

👎Deprecated since 0.17.0: supplemented by external iterator get_slices()

Invokes callback f to handle data in the address range [addr, addr + count).

The address range [addr, addr + count) may span more than one GuestMemoryRegion object, or even have holes in it. So try_access() invokes the callback ‘f’ for each GuestMemoryRegion object involved and returns:

• the error code returned by the callback ‘f’
• the size of the already handled data when encountering the first hole
• the size of the already handled data when the whole range has been handled

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

Get the host virtual address corresponding to the guest address.

Some GuestMemory implementations, like GuestMemoryMmap, have the capability to mmap the guest address range into virtual address space of the host 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.

Arguments

• addr - Guest address to convert.

Examples (uses the backend-mmap feature)

let addr = gm
    .get_host_address(GuestAddress(0x1200))
    .expect("Could not get host address");
println!("Host address is {:p}", addr);

fn get_slice( &self, addr: GuestAddress, count: usize, ) -> Result<VolatileSlice<'_, <<Self::R as GuestMemoryRegion>::B as WithBitmapSlice<'_>>::S>, Error>

Returns a VolatileSlice of count bytes starting at addr.

fn get_slices<'a>( &'a self, addr: GuestAddress, count: usize, ) -> GuestMemorySliceIterator<'a, Self>

Returns an iterator over VolatileSlices, together covering count bytes starting at addr.

Iterating in this way is necessary because the given address range may be fragmented across multiple GuestMemoryRegions.

The iterator’s items are wrapped in [Result], i.e. errors are reported on individual items. If there is no such error, the cumulative length of all items will be equal to count. If count is 0, an empty iterator will be returned.

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<R> GuestMemory for GuestRegionCollection<R>

where R: GuestMemoryRegion,

type R = R