Struct VmWriter

pub struct VmWriter<'a, Fallibility = Fallible> { /* 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, and the corresponding memory writes are infallible. 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, and the corresponding memory writes are considered fallible.

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

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

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

pub fn write(&mut self, reader: &mut VmReader<'_, Infallible>) -> 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 write_once<T: PodOnce>(&mut self, new_val: &T) -> Result<()>

Writes a value of the PodOnce type using one non-tearing memory store.

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

Panics

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

pub fn fill_zeros(&mut self, len: usize) -> usize

Writes len zeros to the target memory.

This method attempts to fill up to len bytes with zeros. If the available memory from the current cursor position is less than len, it will only fill the available space.

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

Converts to a fallible writer.

impl VmWriter<'_, Fallible>

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.

The current context should be consistently associated with valid user space during the entire lifetime 'a. This is for correct semantics and is not a safety requirement.

Safety

ptr must be in user space for len bytes.

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.

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

pub fn atomic_compare_exchange<T>( &self, reader: &VmReader<'_>, old_val: T, new_val: T, ) -> Result<(T, bool)>

where T: PodAtomic + Eq,

Atomically compares and exchanges a PodAtomic value.

This method compares old_val with the value pointed by self and, if they are equal, updates it with new_val.

The value that was previously in memory will be returned, along with a boolean denoting whether the compare-and-exchange succeeds. The caller usually wants to retry if this flag is false, passing the most recent value that was returned by this method.

The caller is required to provide a reader which points to the exact same memory location to ensure that reading from the memory is allowed.

Regardless of whether it is successful, the cursors of the reader and writer 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.

Since the operation does not involve memory locks, it can’t prevent the ABA problem.

This method will fail with errors if:

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

Panics

This method will panic if:

1. the reader and the writer does not point to the same memory location, or
2. the memory location is not aligned on an align_of::<T>()-byte boundary.

pub fn fill_zeros(&mut self, len: usize) -> Result<usize, (Error, usize)>

Writes len zeros to the target memory.

This method attempts to fill up to len bytes with zeros. If the available memory from the current cursor position is less than len, it will only fill the available space.

If the memory write failed due to an unresolvable page fault, this method will return Err with the length set so far.

impl<Fallibility> VmWriter<'_, Fallibility>

pub fn avail(&self) -> usize

Returns the number of bytes for the available space.

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

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

pub fn has_avail(&self) -> bool

Returns if it has available space to write.

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

Limits the length of available space.

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

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

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

Panics

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

Trait Implementations

impl<'a> FallibleVmWrite<Fallible> for VmWriter<'a, Fallible>

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

Writes all data from the reader until one of the three conditions is met:

impl<'a> FallibleVmWrite<Fallible> for VmWriter<'a, Infallible>

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

Writes all data from the reader until one of the three conditions is met:

impl<'a> FallibleVmWrite<Infallible> for VmWriter<'a, Fallible>

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

Writes all data from the reader until one of the three conditions is met:

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

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

Converts to this type from the input type.