Struct base::MemoryMapping

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

See MemoryMapping for struct- and method-level documentation.

Fields

mapping: MemoryMapping

_file_descriptor: Option<SafeDescriptor>

Implementations

impl MemoryMapping

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

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

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

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

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

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

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

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.

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

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

impl MemoryMapping

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

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

pub fn from_raw_ptr( addr: RawDescriptor, size: usize ) -> Result<CrateMemoryMapping>

Trait Implementations

impl Debug for MemoryMapping

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

Formats the value using the given formatter.

impl From<MemoryMapping> for MemoryMappingArena

fn from(mmap: CrateMemoryMapping) -> Self

Converts to this type from the input type.

impl MappedRegion for MemoryMapping

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.

fn size(&self) -> usize

Returns the size of the memory region in bytes.

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.

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

Remove size-byte mapping starting at offset.

impl MemoryMappingUnix for MemoryMapping

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

Remove the specified range from the mapping.

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

Tell the kernel to readahead the range.

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

Tell the kernel to drop the page cache.

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

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

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

Unlock the range of pages.

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

Disable host swap for this mapping.

impl VolatileMemory for MemoryMapping

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.