Module io

Abstractions for reading and writing virtual memory (VM) objects.

Safety

The core virtual memory (VM) access APIs provided by this module are VmReader and VmWriter, which allow for writing to or reading from a region of memory safely. VmReader and VmWriter objects can be constructed from memory regions of either typed memory (e.g., &[u8]) or untyped memory (e.g, UFrame). Behind the scene, VmReader and VmWriter must be constructed via their from_user_space and from_kernel_space methods, whose safety depends on whether the given memory regions are valid or not.

Here is a list of conditions for memory regions to be considered valid:

• The memory region as a whole must be either typed or untyped memory, not both typed and untyped.

• If the memory region is typed, we require that:

  • the validity requirements from the official Rust documentation must be met, and
  • the type of the memory region (which must exist since the memory is typed) must be plain-old-data, so that the writer can fill it with arbitrary data safely.

• If the memory region is untyped, we require that:
  • the underlying pages must remain alive while the validity requirements are in effect, and
  • the kernel must access the memory region using only the APIs provided in this module, but external accesses from hardware devices or user programs do not count.

We have the last requirement for untyped memory to be valid because the safety interaction with other ways to access the memory region (e.g., atomic/volatile memory loads/stores) is not currently specified. Tis may be relaxed in the future, if appropriate and necessary.

Note that data races on untyped memory are explicitly allowed (since pages can be mapped to user space, making it impossible to avoid data races). However, they may produce erroneous results, such as unexpected bytes being copied, but do not cause soundness problems.

Modules

pod_once_impls 🔒

Macros

impl_read_fallible 🔒

impl_vm_io_once_pointer 🔒

impl_vm_io_pointer 🔒

impl_write_fallible 🔒

Structs

VmReader

VmReader is a reader for reading data from a contiguous range of memory.

VmWriter

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

Enums

Fallible

A marker type used for VmReader and VmWriter, representing whether reads or writes on the underlying memory region are fallible.

Infallible

A marker type used for VmReader and VmWriter, representing whether reads or writes on the underlying memory region are infallible.

Traits

FallibleVmRead

Fallible memory read from a VmWriter.

FallibleVmWrite

Fallible memory write from a VmReader.

PodOnce

A marker trait for POD types that can be read or written with one instruction.

VmIo

A trait that enables reading/writing data from/to a VM object, e.g., USegment, Vec<UFrame> and UFrame.

VmIoOnce

A trait that enables reading/writing data from/to a VM object using one non-tearing memory load/store.

Functions

memcpy 🔒 ^⚠

src should be valid for reads of len bytes.dst should be valid for writes of len bytes.

memcpy_fallible 🔒 ^⚠

Copies len bytes from src to dst. This function will early stop copying if encountering an unresolvable page fault.

memset_fallible 🔒 ^⚠

Fills len bytes of memory at dst with the specified value. This function will early stop filling if encountering an unresolvable page fault.