nub_host_kvm/
lib.rs

1/*
2Copyright 2025  The Hyperlight Authors.
3
4Licensed under the Apache License, Version 2.0 (the "License");
5you may not use this file except in compliance with the License.
6You may obtain a copy of the License at
7
8    http://www.apache.org/licenses/LICENSE-2.0
9
10Unless required by applicable law or agreed to in writing, software
11distributed under the License is distributed on an "AS IS" BASIS,
12WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13See the License for the specific language governing permissions and
14limitations under the License.
15*/
16#![warn(dead_code, missing_docs, unused_mut)]
17//! KVM host runtime for executing guest code in lightweight virtual machines.
18//!
19//! This crate provides the host-side runtime for the nub KVM sandbox, enabling
20//! safe execution of untrusted guest code within micro virtual machines with
21//! minimal overhead. The runtime manages sandbox creation, guest function calls,
22//! memory isolation, and host-guest communication over rkyv-encoded RPC.
23//!
24//! The primary entry points are [`UninitializedSandbox`] for initial setup and
25//! [`MultiUseSandbox`] for executing guest functions.
26//!
27//! ## Guest Requirements
28//!
29//! This runtime requires a specially compiled guest binary (the
30//! `nub-arch-guestbin` `x86_64-unknown-none` image) and cannot run regular
31//! container images or executables.
32//!
33
34#![cfg_attr(not(any(test, debug_assertions)), warn(clippy::panic))]
35#![cfg_attr(not(any(test, debug_assertions)), warn(clippy::expect_used))]
36#![cfg_attr(not(any(test, debug_assertions)), warn(clippy::unwrap_used))]
37
38/// Dealing with errors, including errors across VM boundaries
39pub mod error;
40/// Wrappers for host and guest functions.
41pub mod func;
42/// Wrappers for hypervisor implementations
43pub mod hypervisor;
44/// Functionality to establish and manage an individual sandbox's
45/// memory.
46///
47/// - Virtual Address
48///
49/// 0x0000    PML4
50/// 0x1000    PDPT
51/// 0x2000    PD
52/// 0x3000    The guest ELF image (loaded into the sandbox's memory).
53///
54/// - The pointer passed to the Entrypoint in the Guest application is the size of page table + size of code,
55///   at this address structs below are laid out in this order
56pub mod mem;
57/// Metric definitions and helpers
58pub mod metrics;
59/// The main sandbox implementations. Do not use this module directly in code
60/// outside this file. Types from this module needed for public consumption are
61/// re-exported below.
62pub mod sandbox;
63/// Signal handling for Linux
64#[cfg(target_os = "linux")]
65pub(crate) mod signal_handlers;
66// F2.2: `testing/` module dropped (was internal test utilities only).
67
68/// The re-export for the `HyperlightError` type
69pub use error::HyperlightError;
70/// The re-export for the `is_hypervisor_present` type
71pub use hypervisor::virtual_machine::is_hypervisor_present;
72/// A sandbox that can call be used to make multiple calls to guest functions,
73/// and otherwise reused multiple times
74pub use sandbox::MultiUseSandbox;
75/// The re-export for the `UninitializedSandbox` type
76pub use sandbox::UninitializedSandbox;
77/// The re-export for the `GuestBinary` type
78pub use sandbox::uninitialized::GuestBinary;
79
80/// The universal `Result` type used throughout the Hyperlight codebase.
81pub type Result<T> = core::result::Result<T, error::HyperlightError>;
82
83/// Logs an error then returns with it, more or less equivalent to the bail! macro in anyhow
84/// but for HyperlightError instead of anyhow::Error
85#[macro_export]
86macro_rules! log_then_return {
87    ($msg:literal $(,)?) => {{
88        let __args = std::format_args!($msg);
89        let __err_msg = match __args.as_str() {
90            Some(msg) => String::from(msg),
91            None => std::format!($msg),
92        };
93        let __err = $crate::HyperlightError::Error(__err_msg);
94        tracing::error!("{}", __err);
95        return Err(__err);
96    }};
97    ($err:expr $(,)?) => {
98        tracing::error!("{}", $err);
99        return Err($err);
100    };
101    ($err:stmt $(,)?) => {
102        tracing::error!("{}", $err);
103        return Err($err);
104    };
105    ($fmtstr:expr, $($arg:tt)*) => {
106           let __err_msg = std::format!($fmtstr, $($arg)*);
107           let __err = $crate::error::HyperlightError::Error(__err_msg);
108           tracing::error!("{}", __err);
109           return Err(__err);
110    };
111}
112
113/// Same as tracing::debug!, but will additionally print to stdout if the print_debug feature is enabled
114#[macro_export]
115macro_rules! debug {
116    ($($arg:tt)+) =>
117    {
118        #[cfg(print_debug)]
119        println!($($arg)+);
120        tracing::debug!($($arg)+);
121    }
122}
nub_host_kvm/lib.rs

nub_host_kvm/
lib.rs
