nub_host_kvm/

error.rs

/*
Copyright 2025  The Hyperlight Authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

use std::array::TryFromSliceError;
use std::cell::{BorrowError, BorrowMutError};
use std::convert::Infallible;
use std::error::Error;
use std::num::TryFromIntError;
use std::string::FromUtf8Error;
use std::sync::{MutexGuard, PoisonError};
use std::time::SystemTimeError;

use hyperlight_common::flatbuffer_wrappers::function_types::{ParameterValue, ReturnValue};
use hyperlight_common::flatbuffer_wrappers::guest_error::ErrorCode;
use thiserror::Error;

use crate::hypervisor::hyperlight_vm::HyperlightVmError;
use crate::mem::memory_region::MemoryRegionFlags;
use crate::mem::ptr::RawPtr;

/// The error type for Hyperlight operations
#[derive(Error, Debug)]
pub enum HyperlightError {
    /// Anyhow error
    #[error("Anyhow Error was returned: {0}")]
    AnyhowError(#[from] anyhow::Error),
    /// Memory access out of bounds
    #[error("Offset: {0} out of bounds, Max is: {1}")]
    BoundsCheckFailed(u64, usize),

    /// Checked Add Overflow
    #[error("Couldn't add offset to base address. Offset: {0}, Base Address: {1}")]
    CheckedAddOverflow(u64, u64),

    /// CString conversion error
    #[error("Error converting CString {0:?}")]
    CStringConversionError(#[from] std::ffi::NulError),

    /// A generic error with a message
    #[error("{0}")]
    Error(String),

    /// Execution violation
    #[error("Non-executable address {0:#x} tried to be executed")]
    ExecutionAccessViolation(u64),

    /// Guest execution was cancelled by the host
    #[error("Execution was cancelled by the host.")]
    ExecutionCanceledByHost(),

    /// Accessing the value of a flatbuffer parameter failed
    #[error("Failed to get a value from flat buffer parameter")]
    FailedToGetValueFromParameter(),

    ///Field Name not found in decoded GuestLogData
    #[error("Field Name {0} not found in decoded GuestLogData")]
    FieldIsMissingInGuestLogData(String),

    /// Guest aborted during outb
    #[error("Guest aborted: {0} {1}")]
    GuestAborted(u8, String),

    /// Guest call resulted in error in guest
    #[error("Guest error occurred {0:?}: {1}")]
    GuestError(ErrorCode, String),

    /// An attempt to cancel guest execution failed because it is hanging on a host function call
    #[error("Guest execution hung on the execution of a host function call")]
    GuestExecutionHungOnHostFunctionCall(),

    /// Guest call already in progress
    #[error("Guest call is already in progress")]
    GuestFunctionCallAlreadyInProgress(),

    /// The given type is not supported by the guest interface.
    #[error("Unsupported type: {0}")]
    GuestInterfaceUnsupportedType(String),

    /// The guest binary was built against a different guest-bin version than the host expects.
    /// Guest and host versions must match exactly.
    #[error(
        "Guest binary was built with hyperlight-guest-bin {guest_bin_version}, \
         but the host is running hyperlight {host_version}"
    )]
    GuestBinVersionMismatch {
        /// Version of hyperlight-guest-bin the guest was compiled against.
        guest_bin_version: String,
        /// Version of hyperlight-host.
        host_version: String,
    },

    /// A Host function was called by the guest but it was not registered.
    #[error("HostFunction {0} was not found")]
    HostFunctionNotFound(String),

    /// Hyperlight VM error.
    ///
    /// **Note:** This error variant is considered internal and its structure is not stable.
    /// It may change between versions without notice. Users should not rely on this.
    #[doc(hidden)]
    #[error("Internal Hyperlight VM error: {0}")]
    HyperlightVmError(#[from] HyperlightVmError),

    /// Reading Writing or Seeking data failed.
    #[error("Reading Writing or Seeking data failed {0:?}")]
    IOError(#[from] std::io::Error),

    /// Failed to convert to Integer
    #[error("Failed To Convert Size to usize")]
    IntConversionFailure(#[from] TryFromIntError),

    /// Conversion of str to Json failed
    #[error("Conversion of str data to json failed")]
    JsonConversionFailure(#[from] serde_json::Error),

    /// An attempt to get a lock from a Mutex failed.
    #[error("Unable to lock resource")]
    LockAttemptFailed(String),

    /// Memory Access Violation at the given address. The access type and memory region flags are provided.
    #[error("Memory Access Violation at address {0:#x} of type {1}, but memory is marked as {2}")]
    MemoryAccessViolation(u64, MemoryRegionFlags, MemoryRegionFlags),

    /// Memory Allocation Failed.
    #[error("Memory Allocation Failed with OS Error {0:?}.")]
    MemoryAllocationFailed(Option<i32>),

    /// Memory Protection Failed
    #[error("Memory Protection Failed with OS Error {0:?}.")]
    MemoryProtectionFailed(Option<i32>),

    /// Memory region size mismatch
    #[error("Memory region size mismatch: host size {0:?}, guest size {1:?} region {2:?}")]
    MemoryRegionSizeMismatch(usize, usize, String),

    /// The memory request exceeds the maximum size allowed
    #[error("Memory requested {0} exceeds maximum size allowed {1}")]
    MemoryRequestTooBig(usize, usize),

    /// The memory request is too small to contain everything that is
    /// required
    #[error("Memory requested {0} is less than the minimum size allowed {1}")]
    MemoryRequestTooSmall(usize, usize),

    /// Metric Not Found.
    #[error("Metric Not Found {0:?}.")]
    MetricNotFound(&'static str),

    /// mmap Failed.
    #[error("mmap failed with os error {0:?}")]
    MmapFailed(Option<i32>),

    /// mprotect Failed.
    #[error("mprotect failed with os error {0:?}")]
    MprotectFailed(Option<i32>),

    /// No Hypervisor was found for Sandbox.
    #[error("No Hypervisor was found for Sandbox")]
    NoHypervisorFound(),

    /// Failed to get value from parameter value
    #[error("Failed To Convert Parameter Value {0:?} to {1:?}")]
    ParameterValueConversionFailure(ParameterValue, &'static str),

    /// a failure occurred processing a PE file
    #[error("Failure processing PE File {0:?}")]
    PEFileProcessingFailure(#[from] goblin::error::Error),

    /// The sandbox becomes **poisoned** when the guest is not run to completion, leaving it in
    /// an inconsistent state that could compromise memory safety, data integrity, or security.
    ///
    /// ### When Does Poisoning Occur?
    ///
    /// Poisoning happens when guest execution is interrupted before normal completion:
    ///
    /// - **Guest panics or aborts** - When a guest function panics, crashes, or calls `abort()`,
    ///   the normal cleanup and unwinding process is interrupted
    /// - **Invalid memory access** - Attempts to read/write/execute memory outside allowed regions
    /// - **Stack overflow** - Guest exhausts its stack space during execution
    /// - **Heap exhaustion** - Guest runs out of heap memory
    /// - **Host-initiated cancellation** - Calling `InterruptHandle::kill()` to forcefully
    ///   terminate an in-progress guest function
    ///
    /// ## Recovery
    ///
    /// Use `MultiUseSandbox::restore()` to recover from a poisoned sandbox.
    #[error("The sandbox was poisoned")]
    PoisonedSandbox,

    /// Raw pointer is less than base address
    #[error("Raw pointer ({0:?}) was less than the base address ({1})")]
    RawPointerLessThanBaseAddress(RawPtr, u64),

    /// RefCell borrow failed
    #[error("RefCell borrow failed")]
    RefCellBorrowFailed(#[from] BorrowError),

    /// RefCell mut borrow failed
    #[error("RefCell mut borrow failed")]
    RefCellMutBorrowFailed(#[from] BorrowMutError),

    /// Failed to get value from return value
    #[error("Failed To Convert Return Value {0:?} to {1:?}")]
    ReturnValueConversionFailure(ReturnValue, &'static str),

    /// A Hyperlight sandbox was already created in this process. The
    /// KVM substrate supports at most ONE live sandbox per process:
    /// the guest-VA window is a single process-wide reservation
    /// ([`nub_host_common::layout::reserve_guest_va_range`], a
    /// `OnceLock` that silently no-ops on a second call) and every
    /// sandbox `MAP_FIXED`-overlays its kernel-shadow at the one fixed
    /// VA inside it (`FixedVaMapping`, whose `Drop` munmaps it). A
    /// second sandbox — concurrent or sequential — would silently
    /// clobber the first one's live guest memory rather than fail.
    #[error(
        "a Hyperlight sandbox was already created in this process; the KVM substrate supports \
         at most one live sandbox per process (the kernel-shadow is a MAP_FIXED overlay at a \
         single fixed VA inside the one process-wide guest-VA reservation — a second sandbox \
         would silently corrupt the first one's guest memory)"
    )]
    SandboxAlreadyCreated(),

    /// SystemTimeError
    #[error("SystemTimeError {0:?}")]
    SystemTimeError(#[from] SystemTimeError),

    /// Error occurred converting a slice to an array
    #[error("TryFromSliceError {0:?}")]
    TryFromSliceError(#[from] TryFromSliceError),

    /// A function was called with an incorrect number of arguments
    #[error("The number of arguments to the function is wrong: got {0:?} expected {1:?}")]
    UnexpectedNoOfArguments(usize, usize),

    /// The parameter value type is unexpected
    #[error("The parameter value type is unexpected got {0:?} expected {1:?}")]
    UnexpectedParameterValueType(ParameterValue, String),

    /// The return value type is unexpected
    #[error("The return value type is unexpected got {0:?} expected {1:?}")]
    UnexpectedReturnValueType(ReturnValue, String),

    /// Slice conversion to UTF8 failed
    #[error("String Conversion of UTF8 data to str failed")]
    UTF8StringConversionFailure(#[from] FromUtf8Error),

    /// The capacity of the vector is incorrect
    #[error(
        "The capacity of the vector is incorrect. Capacity: {0}, Length: {1}, FlatBuffer Size: {2}"
    )]
    VectorCapacityIncorrect(usize, usize, i32),

    /// vmm sys Error Occurred
    #[error("vmm sys Error {0:?}")]
    #[cfg(target_os = "linux")]
    VmmSysError(vmm_sys_util::errno::Error),
}

impl From<Infallible> for HyperlightError {
    fn from(_: Infallible) -> Self {
        "Impossible as this is an infallible error".into()
    }
}

impl From<&str> for HyperlightError {
    fn from(s: &str) -> Self {
        HyperlightError::Error(s.to_string())
    }
}

impl<T> From<PoisonError<MutexGuard<'_, T>>> for HyperlightError {
    // Implemented this way rather than passing the error as a source to LockAttemptFailed as that would require
    // Box<dyn Error + Send + Sync> which is not easy to implement for PoisonError<MutexGuard<'_, T>>
    // This is a good enough solution and allows use to use the ? operator on lock() calls
    fn from(e: PoisonError<MutexGuard<'_, T>>) -> Self {
        let source = match e.source() {
            Some(s) => s.to_string(),
            None => String::from(""),
        };
        HyperlightError::LockAttemptFailed(source)
    }
}

/// Creates a `HyperlightError::Error` from a string literal or format string
#[macro_export]
macro_rules! new_error {
    ($msg:literal $(,)?) => {{
        let __args = std::format_args!($msg);
        let __err_msg = match __args.as_str() {
            Some(msg) => String::from(msg),
            None => std::format!($msg),
        };
        $crate::HyperlightError::Error(__err_msg)
    }};
    ($fmtstr:expr, $($arg:tt)*) => {{
           let __err_msg = std::format!($fmtstr, $($arg)*);
           $crate::error::HyperlightError::Error(__err_msg)
    }};
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::hypervisor::hyperlight_vm::{
        DispatchGuestCallError, HandleIoError, HyperlightVmError, RunVmError,
    };
    use crate::sandbox::outb::HandleOutbError;

    /// Test that ExecutionCancelledByHost promotes to HyperlightError::ExecutionCanceledByHost
    #[test]
    fn test_promote_execution_cancelled_by_host() {
        let err = DispatchGuestCallError::Run(RunVmError::ExecutionCancelledByHost);
        let (promoted, should_poison) = err.promote();

        assert!(
            should_poison,
            "ExecutionCancelledByHost should poison the sandbox"
        );
        assert!(
            matches!(promoted, HyperlightError::ExecutionCanceledByHost()),
            "Expected HyperlightError::ExecutionCanceledByHost, got {:?}",
            promoted
        );
    }

    /// Test that GuestAborted promotes to HyperlightError::GuestAborted with correct values
    #[test]
    fn test_promote_guest_aborted() {
        let err = DispatchGuestCallError::Run(RunVmError::HandleIo(HandleIoError::Outb(
            HandleOutbError::GuestAborted {
                code: 42,
                message: "test abort".to_string(),
            },
        )));
        let (promoted, should_poison) = err.promote();

        assert!(should_poison, "GuestAborted should poison the sandbox");
        match promoted {
            HyperlightError::GuestAborted(code, msg) => {
                assert_eq!(code, 42);
                assert_eq!(msg, "test abort");
            }
            _ => panic!("Expected HyperlightError::GuestAborted, got {:?}", promoted),
        }
    }

    /// Test that MemoryAccessViolation promotes to HyperlightError::MemoryAccessViolation
    #[test]
    fn test_promote_memory_access_violation() {
        let err = DispatchGuestCallError::Run(RunVmError::MemoryAccessViolation {
            addr: 0xDEADBEEF,
            access_type: MemoryRegionFlags::WRITE,
            region_flags: MemoryRegionFlags::READ,
        });
        let (promoted, should_poison) = err.promote();

        assert!(
            should_poison,
            "MemoryAccessViolation should poison the sandbox"
        );
        match promoted {
            HyperlightError::MemoryAccessViolation(addr, access_type, region_flags) => {
                assert_eq!(addr, 0xDEADBEEF);
                assert_eq!(access_type, MemoryRegionFlags::WRITE);
                assert_eq!(region_flags, MemoryRegionFlags::READ);
            }
            _ => panic!(
                "Expected HyperlightError::MemoryAccessViolation, got {:?}",
                promoted
            ),
        }
    }

    /// Test that non-promoted Run errors are wrapped in HyperlightVmError
    #[test]
    fn test_promote_other_run_errors_wrapped() {
        let err = DispatchGuestCallError::Run(RunVmError::MmioReadUnmapped(0x1000));
        let (promoted, should_poison) = err.promote();

        assert!(should_poison, "Run errors should poison the sandbox");
        assert!(
            matches!(
                promoted,
                HyperlightError::HyperlightVmError(HyperlightVmError::DispatchGuestCall(_))
            ),
            "Expected HyperlightError::HyperlightVmError, got {:?}",
            promoted
        );
    }
}