Struct base::sys::unix::mmap::MemoryMapping

pub struct MemoryMapping {
    addr: *mut u8,
    size: usize,
}

Wraps an anonymous shared memory mapping in the current process. Provides RAII semantics including munmap when no longer needed.

Fields

addr: *mut u8

size: usize

Implementations

impl MemoryMapping

pub fn new(size: usize) -> Result<MemoryMapping, Error>

Creates an anonymous shared, read/write mapping of size bytes.

Arguments

• size - Size of memory region in bytes.

pub fn new_protection(
    size: usize,
    prot: Protection
) -> Result<MemoryMapping, Error>

Creates an anonymous shared mapping of size bytes with prot protection.

Arguments

• size - Size of memory region in bytes.
• prot - Protection (e.g. readable/writable) of the memory region.

pub fn from_fd(
    fd: &dyn AsRawDescriptor,
    size: usize
) -> Result<MemoryMapping, Error>

Maps the first size bytes of the given fd as read/write.

Arguments

• fd - File descriptor to mmap from.
• size - Size of memory region in bytes.

pub fn from_fd_offset(
    fd: &dyn AsRawDescriptor,
    size: usize,
    offset: u64
) -> Result<MemoryMapping, Error>

fn from_fd_offset_flags(
    fd: &dyn AsRawDescriptor,
    size: usize,
    offset: u64,
    flags: c_int,
    prot: Protection
) -> Result<MemoryMapping, Error>

Maps the size bytes starting at offset bytes of the given fd as read/write.

Arguments

• fd - File descriptor to mmap from.
• size - Size of memory region in bytes.
• offset - Offset in bytes from the beginning of fd to start the mmap.
• flags - flags passed directly to mmap.
• prot - Protection (e.g. readable/writable) of the memory region.

pub fn from_fd_offset_protection(
    fd: &dyn AsRawDescriptor,
    size: usize,
    offset: u64,
    prot: Protection
) -> Result<MemoryMapping, Error>

Maps the size bytes starting at offset bytes of the given fd as read/write.

Arguments

• fd - File descriptor to mmap from.
• size - Size of memory region in bytes.
• offset - Offset in bytes from the beginning of fd to start the mmap.
• prot - Protection (e.g. readable/writable) of the memory region.

pub fn from_fd_offset_protection_populate(
    fd: &dyn AsRawDescriptor,
    size: usize,
    offset: u64,
    prot: Protection,
    populate: bool
) -> Result<MemoryMapping, Error>

Maps size bytes starting at offset from the given fd as read/write, and requests that the pages are pre-populated.

Arguments

• fd - File descriptor to mmap from.
• size - Size of memory region in bytes.
• offset - Offset in bytes from the beginning of fd to start the mmap.

pub unsafe fn new_protection_fixed(
    addr: *mut u8,
    size: usize,
    prot: Protection
) -> Result<MemoryMapping, Error>

Creates an anonymous shared mapping of size bytes with prot protection.

Arguments

• addr - Memory address to mmap at.
• size - Size of memory region in bytes.
• prot - Protection (e.g. readable/writable) of the memory region.

Safety

This function should not be called before the caller unmaps any mmap’d regions already present at (addr..addr+size).

pub unsafe fn from_descriptor_offset_protection_fixed(
    addr: *mut u8,
    fd: &dyn AsRawDescriptor,
    size: usize,
    offset: u64,
    prot: Protection
) -> Result<MemoryMapping, Error>

Maps the size bytes starting at offset bytes of the given fd with prot protections.

Arguments

• addr - Memory address to mmap at.
• fd - File descriptor to mmap from.
• size - Size of memory region in bytes.
• offset - Offset in bytes from the beginning of fd to start the mmap.
• prot - Protection (e.g. readable/writable) of the memory region.

Safety

This function should not be called before the caller unmaps any mmap’d regions already present at (addr..addr+size).

unsafe fn try_mmap(
    addr: Option<*mut u8>,
    size: usize,
    prot: c_int,
    flags: c_int,
    fd: Option<(&dyn AsRawDescriptor, u64)>
) -> Result<MemoryMapping, Error>

Helper wrapper around libc::mmap that does some basic validation, and calls madvise with MADV_DONTDUMP on the created mmap

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

Madvise the kernel to unmap on fork.

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

Madvise the kernel to use Huge Pages for this mapping.

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

Calls msync with MS_SYNC on the mapping.

pub fn read_to_memory(
    &self,
    mem_offset: usize,
    src: &dyn AsRawDescriptor,
    count: usize
) -> Result<(), Error>

Reads data from a file descriptor and writes it to guest memory.

Arguments

• mem_offset - Begin writing memory at this offset.
• src - Read from src to memory.
• count - Read count bytes from src to memory.

Examples

• Read bytes from /dev/urandom

      let mut file = File::open(Path::new("/dev/urandom")).map_err(|_| ())?;
      mem_map.read_to_memory(32, &mut file, 128).map_err(|_| ())?;
      let rand_val: u32 =  mem_map.read_obj(40).map_err(|_| ())?;

pub fn write_from_memory(
    &self,
    mem_offset: usize,
    dst: &dyn AsRawDescriptor,
    count: usize
) -> Result<(), Error>

Writes data from memory to a file descriptor.

Arguments

• mem_offset - Begin reading memory from this offset.
• dst - Write from memory to dst.
• count - Read count bytes from memory to src.

Examples

• Write 128 bytes to /dev/null

      let mut file = File::open(Path::new("/dev/null")).map_err(|_| ())?;
      mem_map.write_from_memory(32, &mut file, 128).map_err(|_| ())?;

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

Uses madvise to tell the kernel to remove the specified range. Subsequent reads to the pages in the range will return zero bytes.

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

Tell the kernel to readahead the range.

This does not block the thread by I/O wait from reading the backed file. This does not guarantee that the pages are surely present unless the pages are mlock(2)ed by lock_on_fault_unchecked().

The mem_offset and count must be validated by caller.

Arguments

• mem_offset - The offset of the head of the range.
• count - The size in bytes of the range.

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

Tell the kernel to drop the page cache.

This cannot be applied to locked pages.

The mem_offset and count must be validated by caller.

NOTE: This function has destructive semantics. It throws away data in the page cache without writing it to the backing file. If the data is important, the caller should ensure it is written to disk before calling this function or should use MADV_PAGEOUT instead.

Arguments

• mem_offset - The offset of the head of the range.
• count - The size in bytes of the range.

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

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

The remaining nonresident page are locked when they are populated.

The mem_offset and count must be validated by caller.

Arguments

• mem_offset - The offset of the head of the range.
• count - The size in bytes of the range.

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

Unlock the range of pages.

Unlocking non-locked pages does not fail.

The mem_offset and count must be validated by caller.

Arguments

• mem_offset - The offset of the head of the range.
• count - The size in bytes of the range.

pub(crate) fn range_end(
    &self,
    offset: usize,
    count: usize
) -> Result<usize, Error>

Trait Implementations

impl Debug for MemoryMapping

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

Formats the value using the given formatter.

impl Drop for MemoryMapping

fn drop(&mut self)

Executes the destructor for this type.

impl From<MemoryMapping> for MemoryMappingArena

fn from(mmap: MemoryMapping) -> 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<(), Error>

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

Remove size-byte mapping starting at offset.

impl Send for MemoryMapping

impl Sync for MemoryMapping