Struct base::MemoryMapping

source ·
pub struct MemoryMapping {
    pub(crate) mapping: MemoryMapping,
    pub(crate) _file_descriptor: Option<SafeDescriptor>,
}
Expand description

See MemoryMapping for struct- and method-level documentation.

Fields§

§mapping: MemoryMapping§_file_descriptor: Option<SafeDescriptor>

Implementations§

source§

impl MemoryMapping

source

pub fn write_slice(&self, buf: &[u8], offset: usize) -> Result<usize>

source

pub fn read_slice(&self, buf: &mut [u8], offset: usize) -> Result<usize>

source

pub fn write_obj<T: AsBytes>(&self, val: T, offset: usize) -> Result<()>

Writes an object to the memory region at the specified offset. Returns Ok(()) if the object fits, or Err if it extends past the end.

This method is for writing to regular memory. If writing to a mapped I/O region, use MemoryMapping::write_obj_volatile.

§Examples
  • Write a u64 at offset 16.
    let res = mem_map.write_obj(55u64, 16);
    assert!(res.is_ok());
source

pub fn read_obj<T: FromBytes>(&self, offset: usize) -> Result<T>

Reads on object from the memory region at the given offset. Reading from a volatile area isn’t strictly safe as it could change mid-read. However, as long as the type T is plain old data and can handle random initialization, everything will be OK.

This method is for reading from regular memory. If reading from a mapped I/O region, use MemoryMapping::read_obj_volatile.

§Examples
  • Read a u64 written to offset 32.
    let res = mem_map.write_obj(55u64, 32);
    assert!(res.is_ok());
    let num: u64 = mem_map.read_obj(32).unwrap();
    assert_eq!(55, num);
source

pub fn write_obj_volatile<T: AsBytes>( &self, val: T, offset: usize ) -> Result<()>

Writes an object to the memory region at the specified offset. Returns Ok(()) if the object fits, or Err if it extends past the end.

The write operation will be volatile, i.e. it will not be reordered by the compiler and is suitable for I/O, but must be aligned. When writing to regular memory, prefer MemoryMapping::write_obj.

§Examples
  • Write a u32 at offset 16.
    let res = mem_map.write_obj_volatile(0xf00u32, 16);
    assert!(res.is_ok());
source

pub fn read_obj_volatile<T: FromBytes>(&self, offset: usize) -> Result<T>

Reads on object from the memory region at the given offset. Reading from a volatile area isn’t strictly safe as it could change mid-read. However, as long as the type T is plain old data and can handle random initialization, everything will be OK.

The read operation will be volatile, i.e. it will not be reordered by the compiler and is suitable for I/O, but must be aligned. When reading from regular memory, prefer MemoryMapping::read_obj.

§Examples
  • Read a u32 written to offset 16.
    let res = mem_map.write_obj(0xf00u32, 16);
    assert!(res.is_ok());
    let num: u32 = mem_map.read_obj_volatile(16).unwrap();
    assert_eq!(0xf00, num);
source

pub fn msync(&self) -> Result<()>

source

pub fn flush_region(&self, offset: usize, len: usize) -> Result<()>

Flush a region of the MemoryMapping from the system’s caching hierarchy. There are several uses for flushing:

  • Cached memory which the guest may be reading through an uncached mapping:

    Guest reads via an uncached mapping can bypass the cache and directly access main memory. This is outside the memory model of Rust, which means that even with proper synchronization, guest reads via an uncached mapping might not see updates from the host. As such, it is necessary to perform architectural cache maintainance to flush the host writes to main memory.

    Note that this does not support writable uncached guest mappings, as doing so requires invalidating the cache, not flushing the cache.

  • Uncached memory which the guest may be writing through a cached mapping:

    Guest writes via a cached mapping of a host’s uncached memory may never make it to system/device memory prior to being read. In such cases, explicit flushing of the cached writes is necessary, since other managers of the host’s uncached mapping (e.g. DRM) see no need to flush, as they believe all writes would explicitly bypass the caches.

Currently only supported on x86_64 and aarch64. Cannot be supported on 32-bit arm.

source

pub fn flush_all(&self) -> Result<()>

Flush all backing memory for a mapping in an arch-specific manner (see flush_region()).

source§

impl MemoryMapping

Trait Implementations§

source§

impl Debug for MemoryMapping

source§

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

Formats the value using the given formatter. Read more
source§

impl From<MemoryMapping> for MemoryMappingArena

source§

fn from(mmap: CrateMemoryMapping) -> Self

Converts to this type from the input type.
source§

impl MappedRegion for MemoryMapping

source§

fn as_ptr(&self) -> *mut u8

Returns a pointer to the beginning of the memory region. Should only be used for passing this region to ioctls for setting guest memory.
source§

fn size(&self) -> usize

Returns the size of the memory region in bytes.
source§

fn add_fd_mapping( &mut self, _offset: usize, _size: usize, _fd: &dyn AsRawDescriptor, _fd_offset: u64, _prot: Protection ) -> Result<()>

Maps size bytes starting at fd_offset bytes from within the given fd at offset bytes from the start of the region with prot protections. offset must be page aligned. Read more
source§

fn remove_mapping(&mut self, _offset: usize, _size: usize) -> Result<()>

Remove size-byte mapping starting at offset.
source§

impl MemoryMappingUnix for MemoryMapping

source§

fn remove_range(&self, mem_offset: usize, count: usize) -> Result<()>

Remove the specified range from the mapping.
source§

fn async_prefetch(&self, mem_offset: usize, count: usize) -> Result<()>

Tell the kernel to readahead the range.
source§

fn drop_page_cache(&self, mem_offset: usize, count: usize) -> Result<()>

Tell the kernel to drop the page cache.
source§

fn lock_on_fault(&self, mem_offset: usize, count: usize) -> Result<()>

Lock the resident pages in the range not to be swapped out.
source§

fn unlock(&self, mem_offset: usize, count: usize) -> Result<()>

Unlock the range of pages.
source§

fn lock_all(&self) -> Result<()>

Disable host swap for this mapping.
source§

impl VolatileMemory for MemoryMapping

source§

fn get_slice( &self, offset: usize, count: usize ) -> VolatileMemoryResult<VolatileSlice<'_>>

Gets a slice of memory at offset that is count bytes in length and supports volatile access.

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.