Skip to main content

reverie_kvm/
lib.rs

1/*
2 * Copyright (c) Meta Platforms, Inc. and affiliates.
3 * All rights reserved.
4 *
5 * This source code is licensed under the BSD-style license found in the
6 * LICENSE file in the root directory of this source tree.
7 */
8
9//! Minimal x86-64 KVM primitives for experimenting with a Reverie backend.
10//!
11//! The crate supports the original real-mode transport probes and a bare
12//! long-mode process personality for fixed-address static ELF executables. The
13//! latter implements only a bounded, single-process subset of Linux semantics;
14//! see the crate README for its explicit limits.
15//!
16//! The embedding process must reserve Linux real-time signal 64 exclusively
17//! for this backend. First vCPU entry installs a process-wide handler that is
18//! not restored when a backend is dropped. Existing or later signal ownership
19//! conflicts cause entry errors; these checks do not make concurrent use by
20//! another library safe. A thread that arms a preemption timer also reserves
21//! SIGSTKFLT, which the timer uses only to end `KVM_RUN`: the thread keeps it
22//! blocked outside `KVM_RUN`, so it interrupts no host call. SIGURG remains the
23//! separate worker-cancellation signal. See the crate README for the complete
24//! host signal requirements.
25
26#![cfg(target_arch = "x86_64")]
27
28mod clock;
29mod cpuid_instruction;
30mod entry_driver;
31mod host_xss;
32mod preemption_timer;
33mod runtime;
34mod stats;
35mod step_filter;
36mod timestamp;
37mod tools;
38mod vm;
39
40#[cfg(test)]
41#[path = "entry_cleanup_tests.rs"]
42#[allow(clippy::disallowed_methods, reason = "tests may make threads freely")]
43mod entry_cleanup_tests;
44
45#[cfg(test)]
46#[path = "linuxemu_tests.rs"]
47#[allow(clippy::disallowed_methods, reason = "tests may make threads freely")]
48mod linuxemu_tests;
49
50#[cfg(test)]
51#[path = "../../reverie-linuxemu/tests/support/broker_library_tests.rs"]
52#[expect(
53    dead_code,
54    reason = "this crate's tests use only the cleanup fixture of the shared adapter"
55)]
56mod broker_library_tests;
57
58// LinuxEmu (reverie-linuxemu) and the machine it runs on (reverie-kvm-core),
59// under the names they had when they were modules of this crate.
60pub use memory::GuestMemory;
61pub use reverie::syscalls::Syscall;
62pub use reverie::syscalls::SyscallInfo;
63pub use reverie::syscalls::Sysno;
64pub use reverie_kvm_core::Error;
65use reverie_kvm_core::bootstrap;
66use reverie_kvm_core::entry;
67use reverie_kvm_core::error_ext as error;
68use reverie_kvm_core::failure;
69pub use reverie_kvm_core::host_limits::HostResource;
70use reverie_kvm_core::memory;
71use reverie_kvm_core::supervisor_thread;
72use reverie_kvm_core::syscall;
73use reverie_linuxemu::elf;
74use reverie_linuxemu::executor;
75pub use reverie_linuxemu::native_exit_broker;
76use reverie_linuxemu::provider;
77use reverie_linuxemu::signal;
78#[cfg(test)]
79use reverie_linuxemu::terminal_cleanup;
80use reverie_linuxemu::terminal_read;
81pub use runtime::KvmStack;
82pub use runtime::KvmStackGuard;
83pub use runtime::SyscallExecutor;
84pub use runtime::ToolRunCompletion;
85#[cfg(feature = "native-test-support")]
86pub use runtime::native_test_support;
87pub use stats::KvmBackendStats;
88pub use stats::KvmExitReason;
89pub use syscall::SyscallRequest;
90pub use tools::CounterTool;
91pub use tools::HierarchicalCounter;
92pub use tools::HierarchicalCounterTool;
93pub use tools::HierarchicalTotals;
94pub use tools::StraceEntry;
95pub use tools::StraceLog;
96pub use tools::StraceTool;
97pub use tools::SyscallCounter;
98pub use vm::KvmBackend;
99pub use vm::VMCALL_SYSCALL_TRANSPORT;
100
101/// Result type used by the KVM backend prototype.
102pub type Result<T> = std::result::Result<T, Error>;