Struct ostd::mm::VmReader

pub struct VmReader<'a, Space = KernelSpace> { /* 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. 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.

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, UserSpace>

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

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

1. The reader has no remaining data.
2. The writer has no available space.
3. The reader/writer encounters some error.

On success, the number of bytes read is returned; On error, both the error and the number of bytes read so far are returned.

impl<'a> VmReader<'a, KernelSpace>

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

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

1. The reader has no remaining data.
2. The writer has no available space.
3. The reader/writer encounters some error.

On success, the number of bytes read is returned; On error, both the error and the number of bytes read so far are returned.

impl<'a> VmReader<'a, KernelSpace>

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

Users must ensure the memory from ptr to ptr.add(len) is contiguous. Users must ensure the memory is valid during the entire period of 'a. Users must ensure the memory should not overlap with other VmWriters with typed memory, and if the memory range in this VmReader is typed, it should not overlap with other VmWriters. The user space memory is treated as untyped.

pub fn read(&mut self, writer: &mut VmWriter<'_, KernelSpace>) -> 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.

impl<'a> VmReader<'a, UserSpace>

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

Users must ensure the memory from ptr to ptr.add(len) is contiguous. Users must ensure that the page table for the process in which this constructor is called are active during the entire period of 'a.

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.

impl<'a, Space> VmReader<'a, Space>

pub const fn remain(&self) -> usize

Returns the number of bytes for the remaining data.

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

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

pub const fn has_remain(&self) -> bool

Returns if it has remaining data to read.

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

Limits the length of remaining data.

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

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

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

Panic

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

Trait Implementations

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

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

Converts to this type from the input type.