[−][src]Trait vm_memory::guest_memory::GuestMemory

pub trait GuestMemory {
    type R: GuestMemoryRegion;
    fn num_regions(&self) -> usize;

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

    fn with_regions<F, E>(&self, cb: F) -> Result<(), E>
    where
        F: Fn(usize, &Self::R) -> Result<(), E>;

    fn with_regions_mut<F, E>(&self, cb: F) -> Result<(), E>
    where
        F: FnMut(usize, &Self::R) -> Result<(), E>;

    fn map_and_fold<F, G, T>(&self, init: T, mapf: F, foldf: G) -> T
    where
        F: Fn((usize, &Self::R)) -> T,
        G: Fn(T, T) -> T;

    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>
    where
        F: FnMut(usize, usize, MemoryRegionAddress, &Self::R) -> Result<usize>,
    { ... }

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

    fn get_slice(
        &self, 
        addr: GuestAddress, 
        count: usize
    ) -> Result<VolatileSlice<'_>> { ... }
}

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.

Associated Types

type R: GuestMemoryRegion

Type of objects hosted by the address space.

Loading content...

Required 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 with_regions<F, E>(&self, cb: F) -> Result<(), E> where
    F: Fn(usize, &Self::R) -> Result<(), E>, 

Perform the specified action on each region.

It only walks children of current region and does not step into sub regions.

fn with_regions_mut<F, E>(&self, cb: F) -> Result<(), E> where
    F: FnMut(usize, &Self::R) -> Result<(), E>, 

Perform the specified action on each region mutably.

It only walks children of current region and does not step into sub regions.

fn map_and_fold<F, G, T>(&self, init: T, mapf: F, foldf: G) -> T where
    F: Fn((usize, &Self::R)) -> T,
    G: Fn(T, T) -> T, 

Applies two functions, specified as callbacks, on the inner memory regions.

Arguments

  • init - Starting value of the accumulator for the foldf function.
  • mapf - "Map" function, applied to all the inner memory regions. It returns an array of the same size as the memory regions array, containing the function's results for each region.
  • foldf - "Fold" function, applied to the array returned by mapf. It acts as an operator, applying itself to the init value and to each subsequent elemnent in the array returned by mapf.

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.

    let start_addr1 = GuestAddress(0x0);
    let start_addr2 = GuestAddress(0x400);
    let mem = GuestMemoryMmap::from_ranges(&vec![(start_addr1, 1024), (start_addr2, 2048)])
        .unwrap();
    let total_size = mem.map_and_fold(
        0,
        |(_, region)| region.len() / 1024,
        |acc, size| acc + size
    );
    println!("Total memory size = {} KB", total_size);
    Ok(())
Loading content...

Provided methods

fn last_addr(&self) -> GuestAddress

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

Examples


    let start_addr = GuestAddress(0x1000);
    let mut gm = GuestMemoryMmap::from_ranges(&vec![(start_addr, 0x400)]).map_err(|_| ())?;
    assert_eq!(start_addr.checked_add(0x3ff), Some(gm.last_addr()));
    Ok(())

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> where
    F: FnMut(usize, usize, MemoryRegionAddress, &Self::R) -> Result<usize>, 

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>

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


    let start_addr = GuestAddress(0x1000);
    let mut gm = GuestMemoryMmap::from_ranges(&vec![(start_addr, 0x500)]).map_err(|_| ())?;
    let addr = gm.get_host_address(GuestAddress(0x1200)).unwrap();
    println!("Host address is {:p}", addr);
    Ok(())

test_get_host_address();

fn get_slice(
    &self,
    addr: GuestAddress,
    count: usize
) -> Result<VolatileSlice<'_>>

Returns a VolatileSlice of count bytes starting at addr.

Loading content...

Implementors

Loading content...