ostd/vm/mod.rs
1// SPDX-License-Identifier: MPL-2.0
2
3//! Guest execution and physical memory management.
4//!
5//! OSTD provides safe interfaces for running virtual machines.
6//! A kernel supplies guest memory and CPU state, handles VM exits,
7//! and implements device emulation and scheduling policy.
8//!
9//! # Guest memory
10//!
11//! A [`GuestPhysMemSpace`] maps guest physical addresses ([`Gpaddr`]s)
12//! to host memory backed by untyped frames ([`UFrame`]s).
13//! A kernel can load guest code and data into these frames.
14//! It can query the guest memory mappings through [`gpm_space::Cursor`]
15//! and modify them through [`gpm_space::CursorMut`].
16//!
17//! # Guest execution
18//!
19//! A [`GuestContext`] holds a virtual CPU's (vCPU's) register state.
20//! [`GuestMode::execute`] starts or resumes guest execution in a [`GuestPhysMemSpace`]
21//! from the register state in the supplied context.
22//!
23//! On success, execution returns a [`GuestReturnReason`]:
24//!
25//! - [`GuestReturnReason::VmExit`] carries exit information for the kernel to handle,
26//! such as an I/O access or a guest memory fault.
27//! - [`GuestReturnReason::KernelEvent`] indicates a pending kernel event
28//! reported by [`GuestModeHooks::has_kernel_event`].
29//!
30//! The kernel handles the return reason, updates the guest context as needed,
31//! and calls [`GuestMode::execute`] again to resume the guest.
32//!
33//! [`UFrame`]: crate::mm::UFrame
34//! [`GuestContext`]: crate::arch::vm::GuestContext
35
36pub mod gpm_space;
37mod guest_mode;
38
39pub use self::{
40 gpm_space::GuestPhysMemSpace,
41 guest_mode::{DummyGuestHooks, GuestMode, GuestModeHooks, GuestReturnReason},
42};
43
44/// A guest physical address.
45pub type Gpaddr = usize;