Struct VmWriter

pub struct VmWriter<'a, Fallibility = Fallible> {
    cursor: *mut u8,
    end: *mut u8,
    phantom: PhantomData<(&'a mut [u8], Fallibility)>,
}

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.

Fields

cursor: *mut u8

end: *mut u8

phantom: PhantomData<(&'a mut [u8], Fallibility)>

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.

• ptr should be valid for writes of len bytes.

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<T: Pod>(&mut self, value: T) -> usize

Fills the available space by repeating value.

Returns the number of values written.

Panics

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

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.

• ptr..ptr + len should be within user space.

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 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.