Struct ostd::mm::VmWriter

pub struct VmWriter<'a, Space = KernelSpace> { /* private fields */ }

VmWriter is a writer for writing data to a contiguous range of memory.

The memory range write by VmWriter 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 VmWriter is active for the duration of 'a.

When perform writing with a VmReader, if one of them represents typed memory, it can ensure that the writing range in this writer and reading range in the reader 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> VmWriter<'a, KernelSpace>

pub fn write_fallible( &mut self, reader: &mut VmReader<'_, UserSpace>, ) -> Result<usize, (Error, usize)>

Writes all data from the reader 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 written is returned; On error, both the error and the number of bytes written so far are returned.

impl<'a> VmWriter<'a, UserSpace>

pub fn write_fallible( &mut self, reader: &mut VmReader<'_, KernelSpace>, ) -> Result<usize, (Error, usize)>

Writes all data from the reader 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 written is returned; On error, both the error and the number of bytes written so far are returned.

impl<'a> VmWriter<'a, KernelSpace>

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

Constructs a VmWriter 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 and VmReaders with typed memory, and if the memory range in this VmWriter is typed, it should not overlap with other VmReaders and VmWriters. The user space memory is treated as untyped.

pub fn write(&mut self, reader: &mut VmReader<'_, KernelSpace>) -> usize

Writes all data from the reader 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 written.

pub fn write_val<T: Pod>(&mut self, new_val: &T) -> Result<()>

Writes a value of Pod type.

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

pub fn fill<T: Pod>(&mut self, value: T) -> usize

Fills the available space by repeating value.

Returns the number of values written.

Panic

The size of the available space must be a multiple of the size of value. Otherwise, the method would panic.

impl<'a> VmWriter<'a, UserSpace>

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

Constructs a VmWriter 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 write_val<T: Pod>(&mut self, new_val: &T) -> Result<()>

Writes a value of Pod type.

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

impl<'a, Space> VmWriter<'a, Space>

pub const fn avail(&self) -> usize

Returns the number of bytes for the available space.

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

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

pub const fn has_avail(&self) -> bool

Returns if it has available space to write.

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

Limits the length of available space.

This method ensures the post condition of self.avail() <= max_avail.

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

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

Panic

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

Trait Implementations

impl<'a> From<&'a mut [u8]> for VmWriter<'a>

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

Converts to this type from the input type.