hyperlight-guest-bin 0.17.0

This crate provides the opinionated bits of the guest library, such as the panic handler, the entry point, the guest logger, the exception handling logic, and third-party code used by our C-API needed to build a native hyperlight-guest binary.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

// SPDX-License-Identifier: Apache-2.0
// Copyright 2025 The Hyperlight Authors.

//! This module contains the architecture-specific dispatch function
//! entry sequence

// The extern "C" here is a lie until #![feature(abi_custom)] is stabilised
unsafe extern "C" {
    /// There are two reasons that we need an architecture-specific
    /// assembly stub currently: (1) to ensure that the fact that the
    /// dispatch function never returns but can be executed again is
    /// OK (i.e. we must ensure that there is no stack frame
    /// teardown); (2) at least presently, to ensure that the TLB is
    /// flushed in certain cases.
    ///
    /// # TLB flushing
    ///
    /// The hyperlight host likes to use one partition and reset it in
    /// various ways; if that has happened, there might stale TLB
    /// entries hanging around from the former user of the
    /// partition. Flushing the TLB here is not quite the right thing
    /// to do, since incorrectly cached entries could make even this
    /// code not exist, but regrettably there is not a simple way for
    /// the host to trigger flushing when it ought to happen, so for
    /// now this works in practice, since the text segment is always
    /// part of the big identity-mapped region at the base of the
    /// guest.  The stack, however, is not part of the snapshot region
    /// which is (in practice) idmapped for the relevant area, so this
    /// cannot touch the stack until the flush is done.
    ///
    /// Currently this just always flips CR4.PGE back and forth to
    /// trigger a tlb flush. We should use a faster approach where
    /// available
    ///
    /// # ABI
    ///
    /// The ZF should be set if a TLB flush is required on this call
    /// (e.g. the first call after a snapshot restore)
    ///
    /// The stack pointer should, unusually for amd64, by 16-byte
    /// aligned at the beginning of the function---no return address
    /// should be pushed.
    pub(crate) unsafe fn dispatch_function(must_flush_tlb: u64);
}
core::arch::global_asm!("
    .global dispatch_function
    dispatch_function:
    .cfi_startproc
    .cfi_undefined rip
    jnz flush_done
    mov rdi, cr4
    xor rdi, 0x80
    mov cr4, rdi
    xor rdi, 0x80
    mov cr4, rdi
    flush_done:
    call {internal_dispatch_function}\n
    mov dx, {halt_port}\n
    out dx, eax\n
    cli\n
    hlt\n
    .cfi_endproc
",
    internal_dispatch_function = sym crate::guest_function::call::internal_dispatch_function,
    halt_port = const hyperlight_common::outb::VmAction::Halt as u16,
);