Struct sys_util::MemoryMapping

pub struct MemoryMapping { /* fields omitted */ }

Wraps an anonymous shared memory mapping in the current process.

Methods

impl MemoryMapping

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

Creates an anonymous shared mapping of size bytes.

Arguments

• size - Size of memory region in bytes.

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

Maps the first size bytes of the given fd.

Arguments

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

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

Maps the size bytes starting at offset bytes of the given fd.

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 fn as_ptr(&self) -> *mut u8

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

pub fn size(&self) -> usize

Returns the size of the memory region in bytes.

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

Writes a slice to the memory region at the specified offset. Returns the number of bytes written. The number of bytes written can be less than the length of the slice if there isn't enough room in the memory region.

Examples

• Write a slice at offset 256.

    let res = mem_map.write_slice(&[1,2,3,4,5], 256);
    assert!(res.is_ok());
    assert_eq!(res.unwrap(), 5);

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

Reads to a slice from the memory region at the specified offset. Returns the number of bytes read. The number of bytes read can be less than the length of the slice if there isn't enough room in the memory region.

Examples

• Read a slice of size 16 at offset 256.

    let buf = &mut [0u8; 16];
    let res = mem_map.read_slice(buf, 256);
    assert!(res.is_ok());
    assert_eq!(res.unwrap(), 16);

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

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.

Examples

• Write a u64 at offset 16.

    let res = mem_map.write_obj(55u64, 16);
    assert!(res.is_ok());

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

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.

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 read_to_memory<F>(
    &self,
    mem_offset: usize,
    src: &mut F,
    count: usize
) -> Result<(), Error> where
    F: Read, 

Reads data from a readable object like a File 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<F>(
    &self,
    mem_offset: usize,
    dst: &mut F,
    count: usize
) -> Result<(), Error> where
    F: Write, 

Writes data from memory to a writable object.

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.

Trait Implementations

impl Send for MemoryMapping

impl Drop for MemoryMapping

fn drop(&mut self)

Executes the destructor for this type.

impl Sync for MemoryMapping

impl Debug for MemoryMapping

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

Formats the value using the given formatter.

impl VolatileMemory for MemoryMapping

fn get_slice(
    &self,
    offset: u64,
    count: u64
) -> VolatileMemoryResult<VolatileSlice>

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

fn get_ref<T>(&self, offset: u64) -> Result<VolatileRef<T>, VolatileMemoryError> where
    T: DataInit, 

Gets a VolatileRef at offset.