Struct VmSpace

pub struct VmSpace { /* private fields */ }

A virtual address space for user-mode tasks, enabling safe manipulation of user-space memory.

The VmSpace type provides memory isolation guarantees between user-space and kernel-space. For example, given an arbitrary user-space pointer, one can read and write the memory location referred to by the user-space pointer without the risk of breaking the memory safety of the kernel space.

Task Association Semantics

As far as OSTD is concerned, a VmSpace is not necessarily associated with a task. Once a VmSpace is activated (see VmSpace::activate), it remains activated until another VmSpace is activated possibly by another task running on the same CPU.

This means that it’s up to the kernel to ensure that a task’s VmSpace is always activated while the task is running. This can be done by using the injected post schedule handler (see inject_post_schedule_handler) to always activate the correct VmSpace after each context switch.

If the kernel otherwise decides not to ensure that the running task’s VmSpace is always activated, the kernel must deal with race conditions when calling methods that require the VmSpace to be activated, e.g., UserMode::execute, VmSpace::reader, VmSpace::writer. Otherwise, the behavior is unspecified, though it’s guaranteed not to compromise the kernel’s memory safety.

Memory Backing

A newly-created VmSpace is not backed by any physical memory pages. To provide memory pages for a VmSpace, one can allocate and map physical memory (UFrames) to the VmSpace using the cursor.

A VmSpace can also attach a page fault handler, which will be invoked to handle page faults generated from user space.

Implementations

impl VmSpace

pub fn new() -> Self

Creates a new VM address space.

pub fn cursor<'a, G: AsAtomicModeGuard>( &'a self, guard: &'a G, va: &Range<Vaddr>, ) -> Result<Cursor<'a>>

Gets an immutable cursor in the virtual address range.

The cursor behaves like a lock guard, exclusively owning a sub-tree of the page table, preventing others from creating a cursor in it. So be sure to drop the cursor as soon as possible.

The creation of the cursor may block if another cursor having an overlapping range is alive.

pub fn cursor_mut<'a, G: AsAtomicModeGuard>( &'a self, guard: &'a G, va: &Range<Vaddr>, ) -> Result<CursorMut<'a>>

Gets an mutable cursor in the virtual address range.

The same as Self::cursor, the cursor behaves like a lock guard, exclusively owning a sub-tree of the page table, preventing others from creating a cursor in it. So be sure to drop the cursor as soon as possible.

The creation of the cursor may block if another cursor having an overlapping range is alive. The modification to the mapping by the cursor may also block or be overridden the mapping of another cursor.

pub fn activate(self: &Arc<Self>)

Activates the page table on the current CPU.

pub fn reader(&self, vaddr: Vaddr, len: usize) -> Result<VmReader<'_, Fallible>>

Creates a reader to read data from the user space of the current task.

Returns Err if this VmSpace doesn’t belong to the user space of the current task or the vaddr and len do not represent a user space memory range.

Users must ensure that no other page table is activated in the current task during the lifetime of the created VmReader. This guarantees that the VmReader can operate correctly.

pub fn writer(&self, vaddr: Vaddr, len: usize) -> Result<VmWriter<'_, Fallible>>

Creates a writer to write data into the user space.

Returns Err if this VmSpace doesn’t belong to the user space of the current task or the vaddr and len do not represent a user space memory range.

Users must ensure that no other page table is activated in the current task during the lifetime of the created VmWriter. This guarantees that the VmWriter can operate correctly.

pub fn reader_writer( &self, vaddr: Vaddr, len: usize, ) -> Result<(VmReader<'_, Fallible>, VmWriter<'_, Fallible>)>

Creates a reader/writer pair to read data from and write data into the user space.

Returns Err if this VmSpace doesn’t belong to the user space of the current task or the vaddr and len do not represent a user space memory range.

Users must ensure that no other page table is activated in the current task during the lifetime of the created VmReader and VmWriter. This guarantees that the VmReader and the VmWriter can operate correctly.

This method is semantically equivalent to calling Self::reader and Self::writer separately, but it avoids double checking the validity of the memory region.

Trait Implementations

impl Debug for VmSpace

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for VmSpace

fn default() -> Self

Returns the “default value” for a type.