Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
## [Prerelease] - Unreleased

### Added
* Add `SandboxConfiguration::set_executable_heap` and `SandboxBuilder::executable_heap` to choose heap execution per sandbox. The `executable_heap` Cargo feature sets the default.
* Add `HYPERLIGHT_SURROGATE_EXTRACT_DIR` to configure the surrogate extraction directory on Windows.
* Add `Sandbox::recreate()`, which rebuilds a sandbox's VM and memory from a snapshot. It recovers unrecoverable sandboxes and keeps configuration, host functions, and interrupt handles by @ludfjig in https://github.com/hyperlight-dev/hyperlight/pull/1751

Expand All @@ -17,13 +18,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
* `Snapshot::save` no longer synchronously flushes files to stable storage.
Callers requiring power-loss durability must sync the snapshot files and
directory hierarchy themselves after saving.
* **Breaking:** Snapshots use ABI 10 and config schema v6. Guests must be rebuilt
and existing snapshots regenerated. Guest entry takes the random seed, host
page size, and log level.
* **Breaking:** Snapshots use ABI 12 and config schema v6. Rebuild guests and
regenerate snapshots. Pass a pointer to `StartupArgs` at guest entry.
* **Breaking:** Encode function calls with serde/postcard instead of FlatBuffers.
* Stop resetting guest FPU state between guest calls to improve performance.

### Fixed
* Fix snapshot restores overriding the heap execution setting for newly faulted pages.
* Fix surrogate process creation for Windows paths containing Unicode or spaces.
* Fix restore on WHP not rewinding the guest TSC on hosts with `TSC_ADJUST` support.
* HVF sandbox initialization accepts seeds that match Apple hypercall identifiers.
Expand Down
2 changes: 1 addition & 1 deletion Justfile
Original file line number Diff line number Diff line change
Expand Up @@ -299,7 +299,7 @@ test-isolated target=default-target features="" :

# runs integration tests
test-integration target=default-target features="":
@# run execute_on_heap test with feature "executable_heap" on (runs with off during normal tests)
@# Check the default heap permission with the executable_heap feature enabled.
{{ cargo-cmd }} test {{ if features =="" {"--features executable_heap"} else if features=="no-default-features" {"--no-default-features --features executable_heap"} else {"--no-default-features -F executable_heap," + features } }} --profile={{ if target == "debug" { "dev" } else { target } }} {{ target-triple-flag }} --test integration_test execute_on_heap

@# run component-util unit tests and the integration tests that exercise WIT input codegen
Expand Down
4 changes: 2 additions & 2 deletions docs/hyperlight-metrics-logs-and-traces.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,9 +137,9 @@ runs `no_std` which `opentelemetry` doesn't know.

##### Guest

When the guest starts executing the `entrypoint` function, it receives a `max_log_level` parameter that tells the guest what kind of logging level is expected from it.
At startup, `StartupArgs::max_log_level` sets the guest log filter.

The `trace_guest` logic takes advantage of this parameter and when the `max_log_level` is `trace`, it allocates a custom made `GuestSubscriber` that implements the `Subscriber`
When this field is `trace`, the `trace_guest` logic allocates a custom made `GuestSubscriber` that implements the `Subscriber`
trait from `tracing_core` that allows defining a subscriber for the `tracing` crate to handle new spans and events.

This custom subscriber stores the spans and events in a buffer initialized only when tracing is enabled. For each new span and event, a method is called on the custom subscriber which not only stores the data, but also keeps track of the hierarchy and dependencies between the other spans/events.
Expand Down
4 changes: 4 additions & 0 deletions docs/snapshot-versioning.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,10 @@ host page size, and log level. Earlier snapshots must be regenerated.
ABI 11 encodes control data with postcard and carries its length in a 16-byte
message header. Earlier snapshots must be regenerated.

ABI 12 passes a pointer to `StartupArgs` at guest entry and reserves its storage
in scratch-top metadata. Initialized snapshots keep their heap execution
setting in guest memory. Earlier snapshots must be regenerated.

The `OCI_LAYOUT_VERSION` constant is pinned by the OCI image-layout
spec at `1.0.0`.

Expand Down
29 changes: 23 additions & 6 deletions src/hyperlight_common/src/layout.rs
Original file line number Diff line number Diff line change
Expand Up @@ -21,12 +21,24 @@ const EXN_STACK_ALIGNMENT: usize = 16;
/// Pages reserved for the exception stack and scratch-top metadata.
pub const SCRATCH_TOP_RESERVED_PAGES: usize = 12;

/// Host-written arguments consumed before guest heap initialization.
#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
#[repr(C)]
pub struct StartupArgs {
pub seed: u64,
pub host_page_size: u64,
pub max_log_level: u64,
/// Nonzero if guest heap pages are mapped executable.
pub heap_executable: u64,
}

// Fields are listed in ascending-address order. Public offsets are measured
// down from the top of scratch memory.
#[repr(C)]
struct ScratchTopMetadata {
/// Nonzero if guest heap pages are mapped executable.
heap_executable: u64,
startup_args: StartupArgs,
/// Keeps the exception stack 16-byte aligned.
_alignment_padding: [u8; 8],
/// Host-published capacity of each H2G buffer.
h2g_buffer_size: u64,
/// Number of pages reserved for the H2G pool.
Expand Down Expand Up @@ -85,8 +97,8 @@ pub const SCRATCH_TOP_LIBC_RNG_SEED_OFFSET: u64 =
scratch_top_offset(offset_of!(ScratchTopMetadata, libc_rng_seed));
pub const SCRATCH_TOP_GUEST_LOG_LEVEL_OFFSET: u64 =
scratch_top_offset(offset_of!(ScratchTopMetadata, guest_log_level));
pub const SCRATCH_TOP_HEAP_EXECUTABLE_OFFSET: u64 =
scratch_top_offset(offset_of!(ScratchTopMetadata, heap_executable));
pub const SCRATCH_TOP_STARTUP_ARGS_OFFSET: u64 =
scratch_top_offset(offset_of!(ScratchTopMetadata, startup_args));
pub const SCRATCH_TOP_EXN_STACK_OFFSET: u64 = size_of::<ScratchTopMetadata>() as u64;

const _: () = {
Expand All @@ -107,8 +119,13 @@ const _: () = {
assert!(SCRATCH_TOP_H2G_QUEUE_SIZE_OFFSET == 0x58);
assert!(SCRATCH_TOP_H2G_POOL_PAGES_OFFSET == 0x60);
assert!(SCRATCH_TOP_H2G_BUFFER_SIZE_OFFSET == 0x68);
assert!(SCRATCH_TOP_HEAP_EXECUTABLE_OFFSET == 0x70);
assert!(SCRATCH_TOP_EXN_STACK_OFFSET == 0x70);
assert!(size_of::<StartupArgs>() == 0x20);
assert!(offset_of!(StartupArgs, seed) == 0x00);
assert!(offset_of!(StartupArgs, host_page_size) == 0x08);
assert!(offset_of!(StartupArgs, max_log_level) == 0x10);
assert!(offset_of!(StartupArgs, heap_executable) == 0x18);
assert!(SCRATCH_TOP_STARTUP_ARGS_OFFSET == 0x90);
assert!(SCRATCH_TOP_EXN_STACK_OFFSET == 0x90);

assert!(VIRTQ_BUFFER_GVA_START < VIRTQ_BUFFER_GVA_END);
assert!((VIRTQ_BUFFER_GVA_START as usize).is_multiple_of(crate::vmem::PAGE_SIZE));
Expand Down
3 changes: 0 additions & 3 deletions src/hyperlight_guest/src/layout.rs
Original file line number Diff line number Diff line change
Expand Up @@ -58,9 +58,6 @@ pub fn guest_log_level_gva() -> *mut u64 {
use hyperlight_common::layout::{SCRATCH_TOP_GUEST_LOG_LEVEL_OFFSET, SCRATCH_TOP_GVA};
(SCRATCH_TOP_GVA as u64 - SCRATCH_TOP_GUEST_LOG_LEVEL_OFFSET + 1) as *mut u64
}
pub fn heap_executable_gva() -> *mut u64 {
scratch_top_gva(hyperlight_common::layout::SCRATCH_TOP_HEAP_EXECUTABLE_OFFSET)
}
pub use arch::{scratch_base_gpa, scratch_base_gva};

/// Exclusive upper GPA for the scratch page allocator: the transport arena,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -106,9 +106,7 @@ fn handle_internal_fault(exn: Exception, far: u64, orig_mapping: Option<Mapping>
unsafe { handle_stack_or_heap_fault(far, false) };
true
} else if (HEAP_GVA_START..HEAP_GVA_END).contains(&far) {
// SAFETY: the host writes the scratch-top metadata before entry.
let executable =
unsafe { hyperlight_guest::layout::heap_executable_gva().read_volatile() } != 0;
let executable = crate::HEAP_EXECUTABLE.load(Ordering::Relaxed);
// SAFETY: a translation fault in the heap region means
// the page is unmapped, and exception handling is the
// only page table writer.
Expand Down
17 changes: 13 additions & 4 deletions src/hyperlight_guest_bin/src/arch/aarch64/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -55,17 +55,26 @@ unsafe fn init_vbar() {

/// Machine-specific initialisation; calls [`crate::generic_init`]
/// once VBAR and the main stack have been set up
///
/// # Safety
/// Call once with exclusive access to guest state. `args` must point to an aligned,
/// initialized `StartupArgs` that stays valid until `generic_init` copies it.
#[unsafe(no_mangle)]
pub extern "C" fn entrypoint(seed: u64, ops: u64, max_log_level: u64) -> ! {
pub unsafe extern "C" fn entrypoint(args: *const hyperlight_common::layout::StartupArgs) -> ! {
// SAFETY: the caller guarantees exclusive startup and valid arguments.
unsafe {
init_vbar();
let stack_top = crate::init::init_stack();
pivot_stack(seed, ops, max_log_level, stack_top);
pivot_stack(args, stack_top);
}
}

unsafe extern "C" {
unsafe fn pivot_stack(seed: u64, ops: u64, max_log_level: u64, stack_top: u64) -> !;
/// # Safety
/// `args` must satisfy [`crate::generic_init`]'s safety requirements.
/// `stack_top` must be 16-byte aligned with enough writable stack space below it.
unsafe fn pivot_stack(args: *const hyperlight_common::layout::StartupArgs, stack_top: u64)
-> !;
}

core::arch::global_asm!("
Expand All @@ -77,7 +86,7 @@ core::arch::global_asm!("
msr SPSel, #1\n
mov sp, x5\n
msr SPSel, #0\n
mov sp, x3\n
mov sp, x1\n
bl {generic_init}\n
ldr x1, ={hlt_addr}\n
str x0, [x1]\n
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -133,9 +133,7 @@ fn try_handle_internal_pagefault(
return true;
}
if (HEAP_GVA_START..HEAP_GVA_END).contains(&gva) {
// SAFETY: the host writes the scratch-top metadata before entry.
let executable =
unsafe { hyperlight_guest::layout::heap_executable_gva().read_volatile() } != 0;
let executable = crate::HEAP_EXECUTABLE.load(Ordering::Relaxed);
// SAFETY: the fault is not-present in the heap region, and
// exception handling is the only page table writer.
unsafe { handle_stack_or_heap_pagefault(gva, executable) };
Expand Down
17 changes: 13 additions & 4 deletions src/hyperlight_guest_bin/src/arch/amd64/init.rs
Original file line number Diff line number Diff line change
Expand Up @@ -93,8 +93,13 @@ unsafe fn init_tss(pc: *mut ProcCtrl) {

/// Machine-specific initialisation; calls [`crate::generic_init`]
/// once stack, CoW, etc have been set up.
///
/// # Safety
/// Call once with exclusive access to guest state. `args` must point to an aligned,
/// initialized `StartupArgs` that stays valid until `generic_init` copies it.
#[unsafe(no_mangle)]
pub extern "C" fn entrypoint(seed: u64, ops: u64, max_log_level: u64) {
pub unsafe extern "C" fn entrypoint(args: *const hyperlight_common::layout::StartupArgs) {
// SAFETY: the caller guarantees exclusive startup and valid arguments.
unsafe {
// Allocate a VA for processor control structures which must
// survive snapshotting at the same VA.
Expand All @@ -108,12 +113,16 @@ pub extern "C" fn entrypoint(seed: u64, ops: u64, max_log_level: u64) {
// Architecture early init is complete! We pivot now to
// executing on the main stack, and jump into generic
// initialisation code in lib.rs
pivot_stack(seed, ops, max_log_level, stack_top);
pivot_stack(args, stack_top);
}
}

unsafe extern "C" {
unsafe fn pivot_stack(seed: u64, ops: u64, max_log_level: u64, stack_top: u64) -> !;
/// # Safety
/// `args` must satisfy [`crate::generic_init`]'s safety requirements.
/// `stack_top` must be 16-byte aligned with enough writable stack space below it.
unsafe fn pivot_stack(args: *const hyperlight_common::layout::StartupArgs, stack_top: u64)
-> !;
}

// Mark this as the bottom-most frame for debuggers:
Expand All @@ -129,7 +138,7 @@ core::arch::global_asm!("
pivot_stack:\n
.cfi_startproc\n
.cfi_undefined rip\n
mov rsp, rcx\n
mov rsp, rsi\n
xor ebp, ebp\n
call {generic_init}\n
mov dx, {halt_port}\n
Expand Down
23 changes: 19 additions & 4 deletions src/hyperlight_guest_bin/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
extern crate alloc;

use core::fmt::Write;
use core::sync::atomic::{AtomicBool, Ordering, compiler_fence};

use arch::dispatch::dispatch_function;
use guest_function::register::GuestFunctionRegister;
Expand Down Expand Up @@ -114,6 +115,8 @@ pub(crate) static HEAP_ALLOCATOR: GuestHeap = GuestHeap::new(Manual);
#[global_allocator]
pub(crate) static HEAP_ALLOCATOR: ProfiledLockedHeap = ProfiledLockedHeap(GuestHeap::new(Manual));

pub(crate) static HEAP_EXECUTABLE: AtomicBool = AtomicBool::new(false);

pub(crate) static mut REGISTERED_GUEST_FUNCTIONS: GuestFunctionRegister<GuestFunc> =
GuestFunctionRegister::new();

Expand Down Expand Up @@ -251,7 +254,19 @@ core::arch::global_asm!(
/// Architecture-nonspecific initialisation: set up the heap,
/// coordinate some addresses and configuration with the host, and run
/// user initialisation
pub(crate) extern "C" fn generic_init(_seed: u64, ops: u64, max_log_level: u64) -> u64 {
///
/// # Safety
/// Call once with exclusive access to guest state. `args` must point to an aligned,
/// initialized `StartupArgs` that stays valid until copied.
pub(crate) unsafe extern "C" fn generic_init(
args: *const hyperlight_common::layout::StartupArgs,
) -> u64 {
// SAFETY: the caller guarantees an aligned, initialized value at args.
let args = unsafe { args.read() };
HEAP_EXECUTABLE.store(args.heap_executable != 0, Ordering::Relaxed);
// Heap initialization faults into handlers that read this flag.
compiler_fence(Ordering::SeqCst);

unsafe {
#[cfg(not(all(feature = "mem_profile", target_arch = "x86_64")))]
let heap_allocator = &HEAP_ALLOCATOR;
Expand All @@ -276,19 +291,19 @@ pub(crate) extern "C" fn generic_init(_seed: u64, ops: u64, max_log_level: u64)

#[cfg(feature = "libc")]
unsafe {
srand(_seed as u32);
srand(args.seed as u32);
}

unsafe {
OS_PAGE_SIZE = ops as u32;
OS_PAGE_SIZE = args.host_page_size as u32;
}

// Prepare transport before logging or guest initialization code can use it.
transport::initialize();

// set up the logger
let guest_log_level_filter =
GuestLogFilter::try_from(max_log_level).expect("Invalid log level");
GuestLogFilter::try_from(args.max_log_level).expect("Invalid log level");
init_logger(guest_log_level_filter.into());

// It is important that all the tracing events are produced after the tracing is initialized.
Expand Down
7 changes: 2 additions & 5 deletions src/hyperlight_host/src/hypervisor/hyperlight_vm/aarch64.rs
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,6 @@ use crate::hypervisor::LinuxInterruptHandle;
use crate::hypervisor::WindowsInterruptHandle;
#[cfg(gdb)]
use crate::hypervisor::gdb::{DebugCommChannel, DebugMsg, DebugResponse};
use crate::hypervisor::hyperlight_vm::get_guest_log_filter;
use crate::hypervisor::regs::{CommonRegisters, CommonSpecialRegisters};
#[cfg(hvf)]
use crate::hypervisor::virtual_machine::hvf::HvfVm;
Expand Down Expand Up @@ -112,15 +111,13 @@ impl HyperlightVm {
seed: u64,
mem_mgr: &mut SandboxMemoryManager<HostSharedMemory>,
host_funcs: &Arc<std::sync::Mutex<FunctionRegistry>>,
guest_max_log_level: Option<tracing_core::LevelFilter>,
config: &SandboxConfiguration,
) -> Result<(), InitializeError> {
let NextAction::Initialise(initialise) = self.next_action else {
return Ok(());
};
let mut x: [u64; 31] = [0; 31];
x[0] = seed;
x[1] = self.page_size as u64;
x[2] = get_guest_log_filter(guest_max_log_level);
x[0] = self.write_startup_args(seed, mem_mgr, config)?;
let regs = CommonRegisters {
pc: initialise,
sp: self.rsp_gva,
Expand Down
22 changes: 22 additions & 0 deletions src/hyperlight_host/src/hypervisor/hyperlight_vm/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ use crate::mem::memory_region::{MemoryRegion, MemoryRegionFlags, MemoryRegionTyp
use crate::mem::mgr::SandboxMemoryManager;
use crate::mem::shared_mem::{GuestSharedMemory, HostSharedMemory, SharedMemory};
use crate::metrics::{METRIC_ERRONEOUS_VCPU_KICKS, METRIC_GUEST_CANCELLATION};
use crate::sandbox::SandboxConfiguration;
use crate::sandbox::host_funcs::FunctionRegistry;
use crate::sandbox::outb::{HandleOutbError, handle_outb};
use crate::sandbox::snapshot::{NextAction, SnapshotMemoryBacking};
Expand Down Expand Up @@ -108,6 +109,25 @@ pub(super) fn get_guest_log_filter(guest_max_log_level: Option<LevelFilter>) ->
GuestLogFilter::from(guest_log_level_filter).into()
}

impl HyperlightVm {
fn write_startup_args(
&self,
seed: u64,
mem_mgr: &mut SandboxMemoryManager<HostSharedMemory>,
config: &SandboxConfiguration,
) -> Result<u64, InitializeError> {
let args = hyperlight_common::layout::StartupArgs {
seed,
host_page_size: self.page_size as u64,
max_log_level: get_guest_log_filter(config.get_max_guest_log_level()),
heap_executable: u64::from(config.get_executable_heap()),
};
mem_mgr
.write_startup_args(args)
.map_err(|error| InitializeError::WriteStartupArgs(Box::new(error)))
}
}

/// DispatchGuestCall error
#[derive(Debug, thiserror::Error)]
pub enum DispatchGuestCallError {
Expand Down Expand Up @@ -164,6 +184,8 @@ impl DispatchGuestCallError {
pub enum InitializeError {
#[error("Failed to convert pointer: {0}")]
ConvertPointer(String),
#[error("Failed to write guest startup arguments: {0}")]
WriteStartupArgs(Box<HyperlightError>),
#[error("Failed to run vm: {0}")]
Run(#[from] RunVmError),
#[error("Failed to setup registers: {0}")]
Expand Down
11 changes: 6 additions & 5 deletions src/hyperlight_host/src/hypervisor/hyperlight_vm/x86_64.rs
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ use std::collections::HashMap;
use std::sync::{Arc, Mutex};

use tracing::{Span, instrument};
#[cfg(test)]
use tracing_core::LevelFilter;

use super::*;
Expand Down Expand Up @@ -171,11 +172,12 @@ impl HyperlightVm {
seed: u64,
mem_mgr: &mut SandboxMemoryManager<HostSharedMemory>,
host_funcs: &Arc<Mutex<FunctionRegistry>>,
guest_max_log_level: Option<LevelFilter>,
config: &SandboxConfiguration,
) -> std::result::Result<(), InitializeError> {
let NextAction::Initialise(initialise) = self.next_action else {
return Ok(());
};
let startup_args = self.write_startup_args(seed, mem_mgr, config)?;

let regs = CommonRegisters {
rip: initialise,
Expand All @@ -188,9 +190,7 @@ impl HyperlightVm {
rsp: self.rsp_gva - 8,

// function args
rdi: seed,
rsi: self.page_size as u64,
rdx: get_guest_log_filter(guest_max_log_level),
rdi: startup_args,
rflags: 1 << 1,

..Default::default()
Expand Down Expand Up @@ -1491,7 +1491,8 @@ mod tests {

let host_funcs = Arc::new(Mutex::new(FunctionRegistry::default()));

vm.initialise(seed, &mut hshm, &host_funcs, None).unwrap();
vm.initialise(seed, &mut hshm, &host_funcs, &config)
.unwrap();

TestVmContext {
vm,
Expand Down
Loading
Loading