Struct VmReader

pub struct VmReader<'a, Fallibility = Fallible> { /* private fields */ }

VmReader is a reader for reading data from a contiguous range of memory.

The memory range read by VmReader can be in either kernel space or user space. When the operating range is in kernel space, the memory within that range is guaranteed to be valid, and the corresponding memory reads are infallible. When the operating range is in user space, it is ensured that the page table of the process creating the VmReader is active for the duration of 'a, and the corresponding memory reads are considered fallible.

When perform reading with a VmWriter, if one of them represents typed memory, it can ensure that the reading range in this reader and writing range in the writer are not overlapped.

NOTE: The overlap mentioned above is at both the virtual address level and physical address level. There is not guarantee for the operation results of VmReader and VmWriter in overlapping untyped addresses, and it is the user’s responsibility to handle this situation.

Implementations

impl<'a> VmReader<'a, Infallible>

pub unsafe fn from_kernel_space(ptr: *const u8, len: usize) -> Self

Constructs a VmReader from a pointer and a length, which represents a memory range in kernel space.

Safety

ptr must be valid for reads of len bytes during the entire lifetime a.

pub fn read(&mut self, writer: &mut VmWriter<'_, Infallible>) -> usize

Reads all data into the writer until one of the two conditions is met:

1. The reader has no remaining data.
2. The writer has no available space.

Returns the number of bytes read.

pub fn read_val<T: Pod>(&mut self) -> Result<T>

Reads a value of Pod type.

If the length of the Pod type exceeds self.remain(), this method will return Err.

pub fn read_once<T: PodOnce>(&mut self) -> Result<T>

Reads a value of the PodOnce type using one non-tearing memory load.

If the length of the PodOnce type exceeds self.remain(), this method will return Err.

This method will not compile if the Pod type is too large for the current architecture and the operation must be tear into multiple memory loads.

Panics

This method will panic if the current position of the reader does not meet the alignment requirements of type T.

pub fn to_fallible(self) -> VmReader<'a, Fallible>

Converts to a fallible reader.

impl VmReader<'_, Fallible>

pub unsafe fn from_user_space(ptr: *const u8, len: usize) -> Self

Constructs a VmReader from a pointer and a length, which represents a memory range in user space.

Safety

The virtual address range ptr..ptr + len must be in user space.

pub fn read_val<T: Pod>(&mut self) -> Result<T>

Reads a value of Pod type.

If the length of the Pod type exceeds self.remain(), or the value can not be read completely, this method will return Err.

If the memory read failed, this method will return Err and the current reader’s cursor remains pointing to the original starting position.

pub fn atomic_load<T: PodAtomic>(&self) -> Result<T>

Atomically loads a PodAtomic value.

Regardless of whether it is successful, the cursor of the reader will not move.

This method only guarantees the atomicity of the specific operation. There are no synchronization constraints on other memory accesses. This aligns with the Relaxed ordering specified in the C++11 memory model.

This method will fail with errors if

1. the remaining space of the reader is less than size_of::<T>() bytes, or
2. the memory operation fails due to an unresolvable page fault.

Panics

This method will panic if the memory location is not aligned on an align_of::<T>()-byte boundary.

impl<Fallibility> VmReader<'_, Fallibility>

pub fn remain(&self) -> usize

Returns the number of bytes for the remaining data.

pub fn cursor(&self) -> *const u8

Returns the cursor pointer, which refers to the address of the next byte to read.

pub fn has_remain(&self) -> bool

Returns if it has remaining data to read.

pub fn limit(&mut self, max_remain: usize) -> &mut Self

Limits the length of remaining data.

This method ensures the post condition of self.remain() <= max_remain.

pub fn skip(&mut self, nbytes: usize) -> &mut Self

Skips the first nbytes bytes of data. The length of remaining data is decreased accordingly.

Panics

If nbytes is greater than self.remain(), then the method panics.

Trait Implementations

impl<Fallibility> Clone for VmReader<'_, Fallibility>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> FallibleVmRead<Fallible> for VmReader<'a, Fallible>

fn read_fallible( &mut self, writer: &mut VmWriter<'_, Fallible>, ) -> Result<usize, (Error, usize)>

Reads all data into the writer until one of the three conditions is met:

impl<'a> FallibleVmRead<Fallible> for VmReader<'a, Infallible>

fn read_fallible( &mut self, writer: &mut VmWriter<'_, Fallible>, ) -> Result<usize, (Error, usize)>

Reads all data into the writer until one of the three conditions is met:

impl<'a> FallibleVmRead<Infallible> for VmReader<'a, Fallible>

fn read_fallible( &mut self, writer: &mut VmWriter<'_, Infallible>, ) -> Result<usize, (Error, usize)>

Reads all data into the writer until one of the three conditions is met:

impl<'a> From<&'a [u8]> for VmReader<'a, Infallible>

fn from(slice: &'a [u8]) -> Self

Converts to this type from the input type.