baryl 0.0.2

//! The `#[repr(C)]` vocabulary the rest of the SDK is written in.
//!
//! Guest addresses ([`VirtAddr`], [`PhysAddr`]), typed pointers into the run's
//! pool ([`SbxPtr`], [`AnonPtr`], [`SbxArray`]), the two collections that can
//! cross between separately built binaries (`BVec`, `BMap`), the inline string
//! a C header spells `char[N]` ([`FlatCStr`]), the [`VMCall`] body, the bounds
//! one scan takes ([`ScanRange`]), and the macros that build hashed
//! discriminants and tame raw pointers.
//!
//! The names a component reaches for most are re-exported at the crate root, so
//! `use baryl::VirtAddr` and `use baryl::abi::VirtAddr` name the same type.
//! Every `macro_rules!` here is exported at the crate root as well —
//! `baryl::as_ref!`, `baryl::tag_enum!` — and named again in this module, so
//! either path imports it.

// Bindgen output cannot satisfy the workspace lints; the allow stops here.
mod generated {
    #![allow(non_camel_case_types, non_upper_case_globals, dead_code)]
    include!("generated.rs");
}
pub use generated::*;

mod addr;
mod collections;
mod sandbox;
mod scan;
mod utils;
mod vmcall;

/// The exported macros, named here as well as at the crate root.
pub use crate::{
    as_mut, as_ref, impl_sandbox_safe, newtype_ops, slice, slice_mut, tag_enum, vmcall_enum,
    write_field,
};
pub use addr::*;
pub use collections::*;
pub use sandbox::SandboxSafe;
pub use scan::*;
pub use utils::*;
pub use vmcall::*;

use std::{
    cmp::Ordering,
    ffi::CStr,
    fmt,
    hash::{Hash, Hasher},
    ops::{Add, Deref, DerefMut, Range, Sub},
    ptr::copy_nonoverlapping,
};

#[cfg(feature = "component")]
use std::{
    simd::Simd,
    slice::{from_raw_parts, from_raw_parts_mut},
};

#[cfg(feature = "component")]
use gxhash::GxHasher;

/// A guest memory access that did not happen, and the address it stopped on.
///
/// Implements `Display` and `std::error::Error`; the message names the address.
#[derive(Debug, Clone, Copy)]
pub enum MemAccessError {
    /// Nothing is mapped at this guest virtual address under the page-table
    /// root the call was made with.
    UnmappedVirt(VirtAddr),
    /// This guest physical address falls outside every RAM region the machine
    /// has.
    UnmappedPhys(PhysAddr),
    /// The range spans two 4 KiB pages, and the call that took it reads one
    /// page at a time.
    CrossesPageBoundary { addr: VirtAddr, len: usize },
    /// The bytes at this address are not a valid value of the type they were
    /// asked for — too few of them, or the wrong alignment.
    InvalidRef(VirtAddr),
}

impl fmt::Display for MemAccessError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::UnmappedVirt(va) => write!(f, "unmapped guest VA {va:?}"),
            Self::UnmappedPhys(pa) => write!(f, "unmapped guest PA {pa:?}"),
            Self::CrossesPageBoundary { addr, len } => {
                write!(f, "range of {len} bytes at {addr:?} crosses a page boundary")
            },
            Self::InvalidRef(va) => write!(f, "invalid typed reference at {va:?}"),
        }
    }
}

impl std::error::Error for MemAccessError {}

/// Why arming a breakpoint was refused.
///
/// Returned by `BreakpointsRef::insert`. Implements `Display` and
/// `std::error::Error`; the message names the site.
#[derive(Debug, Clone, Copy)]
pub enum BpInsertError {
    /// You already hold a breakpoint at this site. Several components may each
    /// watch one address; the same one may not claim it twice.
    DuplicateOwner(PhysAddr),
}

impl fmt::Display for BpInsertError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::DuplicateOwner(pa) => {
                write!(f, "breakpoint at {pa:?} already owned by this component")
            },
        }
    }
}

impl std::error::Error for BpInsertError {}

/// Fixed seed for `hash64`, so a `BMap` probes the same slots every run.
#[cfg(feature = "component")]
const SEED: i64 = 0x52c8_611d_3941_be6a_u64 as i64;

/// The 64-bit hash `BMap` keys on.
#[cfg(feature = "component")]
pub(crate) fn hash64<T: Hash + ?Sized>(data: &T) -> u64 {
    let mut hasher = GxHasher::with_seed(SEED);
    data.hash(&mut hasher);
    hasher.finish()
}

// Pointer hygiene: the conversions a callback's raw arguments ask for

/// `&*p`, written without an `unsafe` block at the call site.
///
/// The `unsafe` is inside the expansion, so the promise is yours to keep: `p`
/// must be non-null, aligned, and point at a live initialized value for as long
/// as the reference is held. Every pointer an event handler is passed satisfies
/// that for the length of that call and no longer.
///
/// # Examples
///
/// ```ignore
/// use baryl::{arch::GuestAddr, as_ref};
///
/// unsafe extern "C" fn on_novel_block(_obj: *mut c_void, _ctl: *mut Control, key: *const GuestAddr) {
///     let key: &GuestAddr = as_ref!(key);
///     baryl::logging::info!("new block at {:#x} under cr3 {:#x}", key.va, key.cr3);
/// }
/// ```
#[macro_export]
macro_rules! as_ref {
    ($p:expr) => {
        // SAFETY: the ABI hands this pointer live and aligned for the call.
        unsafe { &*$p }
    };
}

/// `&mut *p`, written without an `unsafe` block at the call site.
///
/// Same promise as [`as_ref!`](crate::as_ref), plus exclusivity: nothing else may read or
/// write through `p` while the returned reference is alive.
///
/// The argument is evaluated *outside* the `unsafe` block, so an argument that
/// is itself an unsafe operation needs its own `unsafe { … }`.
#[macro_export]
macro_rules! as_mut {
    ($p:expr) => {{
        let p = $p;
        // SAFETY: the ABI hands this pointer live and aligned for the call.
        unsafe { &mut *p }
    }};
}

/// Write `value` into one field of `*p` without ever forming a reference to
/// the whole struct.
///
/// Reach for this instead of `as_mut!(p).field = value` when anything may
/// already hold a pointer into `*p` — a `&mut` covering the struct invalidates
/// every such pointer, and this never makes one. The field may be nested.
///
/// Same promise as [`as_mut!`](crate::as_mut) for `p`, minus the whole-struct exclusivity:
/// only the named field is written.
///
/// # Examples
///
/// ```ignore
/// write_field!(vtable, insert, Some(my_insert));
/// write_field!(descriptor, core.on_exit, Some(my_exit));
/// ```
#[macro_export]
macro_rules! write_field {
    ($p:expr, $($field:ident).+, $value:expr) => {
        // SAFETY: the ABI hands this pointer live and aligned, as for `as_mut!`.
        unsafe { (&raw mut (*$p).$($field).+).write($value) }
    };
}

/// `&[T]` over `len` elements at `p`, written without an `unsafe` block.
///
/// `len` may be any integer type: it is cast with `as usize`. A negative signed
/// length therefore becomes an enormous positive one rather than an error, so
/// check a length that came from the guest before passing it.
///
/// # Examples
///
/// ```ignore
/// unsafe extern "C" fn on_guest_tx(_obj: *mut c_void, _ctl: *mut Control, frame: *const u8, len: u64) {
///     let frame: &[u8] = slice!(frame, len);
///     baryl::logging::info!("{} byte frame, first octet {:#x}", frame.len(), frame[0]);
/// }
/// ```
#[macro_export]
macro_rules! slice {
    ($p:expr, $len:expr) => {
        // SAFETY: the caller supplies `len` readable elements at `p`.
        unsafe { ::core::slice::from_raw_parts($p, $len as usize) }
    };
}

/// `&mut [T]` over `len` elements at `p`. [`slice!`](crate::slice), with exclusive access and
/// the same `as usize` cast on `len`.
#[macro_export]
macro_rules! slice_mut {
    ($p:expr, $len:expr) => {
        // SAFETY: the caller supplies `len` writable elements at `p`.
        unsafe { ::core::slice::from_raw_parts_mut($p, $len as usize) }
    };
}

macro_rules! pool_ptr {
    ($Name:ident) => {
        /// A typed pointer into the run's pool.
        ///
        /// Two of these exist, differing only in which region they address.
        /// `SbxPtr` points at checkpointed memory: those bytes are written into
        /// every `.ck` and come back on restore. `AnonPtr` points at memory
        /// remapped fresh each run: the *address* survives a restore, the bytes
        /// do not, and a restored run reads zeroes there until something writes
        /// them again.
        ///
        /// Nothing here is bounds-checked, and almost none of it is `unsafe`:
        /// dereferencing, slicing and `copy_from_slice` read or write through
        /// the address exactly as given. Staying inside the allocation
        /// `AllocRef::leak_and_initialize_sbx` or `..._anon` handed you is
        /// yours to enforce.
        ///
        /// `Copy`, `Send` and `Sync`. Equality, ordering and hashing are the
        /// address alone, and `Debug`/`LowerHex` print it in hex.
        #[repr(transparent)]
        pub struct $Name<T>(*mut T);

        unsafe impl<T> Send for $Name<T> {}
        unsafe impl<T> Sync for $Name<T> {}

        impl<T> Copy for $Name<T> {}
        impl<T> Clone for $Name<T> {
            fn clone(&self) -> Self {
                *self
            }
        }

        impl<T> $Name<T> {
            /// Put a type on a raw address — a register value, a syscall
            /// argument, a number read out of the guest. Nothing is checked;
            /// the address is taken as given.
            pub fn from_addr(addr: u64) -> Self {
                Self(addr as usize as *mut T)
            }

            /// Wrap a pointer you already hold.
            ///
            /// # Safety
            /// `ptr` must address pool memory that stays live for as long as
            /// this handle is used.
            pub unsafe fn from_raw(ptr: *mut T) -> Self {
                Self(ptr)
            }

            /// The address as a plain `*mut T`.
            pub fn as_raw_ptr(&self) -> *mut T {
                self.0
            }

            /// The address as a number — what a vmcall body or a log line wants.
            pub fn to_u64(&self) -> u64 {
                self.0 as u64
            }

            /// True for address 0. Nothing else is checked.
            pub fn is_null(&self) -> bool {
                self.0.is_null()
            }

            /// The same address, read as a pointer to `U`. Neither size nor
            /// alignment is checked: this is a relabel, not a conversion.
            pub fn cast<U>(self) -> $Name<U> {
                $Name(self.0 as *mut U)
            }

            /// Move forward by `offset` **bytes**, not elements, keeping the
            /// type. Wraps at the end of the address space rather than
            /// panicking. `p + n` is this, so `p + 8` on an `SbxPtr<u64>`
            /// advances one element, not eight.
            pub fn byte_add(self, offset: usize) -> Self {
                Self(self.0.wrapping_byte_add(offset))
            }
        }

        impl $Name<u8> {
            /// `len` bytes at this address. Unchecked: `len` is trusted to fit
            /// the allocation.
            pub fn as_slice(&self, len: usize) -> &[u8] {
                unsafe { core::slice::from_raw_parts(self.0, len) }
            }

            /// The same bytes, writable. Unchecked, as `as_slice`.
            pub fn as_mut_slice(&mut self, len: usize) -> &mut [u8] {
                unsafe { core::slice::from_raw_parts_mut(self.0, len) }
            }

            /// Write `src` at this address. Writes `src.len()` bytes with no
            /// length check at all, and the two regions must not overlap. Use
            /// `SbxArray::copy_from_slice`, which carries a length and asserts
            /// on a mismatch, wherever the size is not already fixed.
            pub fn copy_from_slice(&self, src: &[u8]) {
                unsafe { copy_nonoverlapping(src.as_ptr(), self.0, src.len()) };
            }

            /// The bytes up to the first NUL. Reads past the allocation if
            /// there is no NUL in it.
            pub fn as_cstr(&self) -> &CStr {
                unsafe { CStr::from_ptr(self.0 as *const core::ffi::c_char) }
            }
        }

        impl<T> Deref for $Name<T> {
            type Target = T;
            fn deref(&self) -> &T {
                unsafe { &*self.0 }
            }
        }

        impl<T> DerefMut for $Name<T> {
            fn deref_mut(&mut self) -> &mut T {
                unsafe { &mut *self.0 }
            }
        }

        impl<T> fmt::Debug for $Name<T> {
            fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
                write!(f, "{}({:#x})", stringify!($Name), self.0 as usize)
            }
        }

        impl<T> fmt::LowerHex for $Name<T> {
            fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
                fmt::LowerHex::fmt(&(self.0 as usize), f)
            }
        }

        impl<T> PartialEq for $Name<T> {
            fn eq(&self, other: &Self) -> bool {
                self.0 == other.0
            }
        }
        impl<T> Eq for $Name<T> {}

        impl<T> PartialOrd for $Name<T> {
            fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
                Some(self.cmp(other))
            }
        }

        impl<T> Ord for $Name<T> {
            fn cmp(&self, other: &Self) -> Ordering {
                (self.0 as usize).cmp(&(other.0 as usize))
            }
        }

        impl<T> Hash for $Name<T> {
            fn hash<H: Hasher>(&self, state: &mut H) {
                (self.0 as usize).hash(state);
            }
        }

        impl<T> Add<usize> for $Name<T> {
            type Output = Self;
            fn add(self, rhs: usize) -> Self {
                self.byte_add(rhs)
            }
        }

        impl<T> Sub<$Name<T>> for $Name<T> {
            type Output = usize;
            /// The distance in **bytes** from `rhs` up to `self`. `rhs` must be
            /// the lower address; the other way round underflows.
            fn sub(self, rhs: Self) -> usize {
                (self.0 as usize) - (rhs.0 as usize)
            }
        }
    };
}

pool_ptr!(SbxPtr);
pool_ptr!(AnonPtr);

// Pool arrays: a pointer and a length, side by side

/// Bytes `simd_memcpy` moves per step; `portable_simd` lowers a 64-lane `u8`
/// vector onto whatever registers the target has.
#[cfg(feature = "component")]
const MEMCPY_LANES: usize = 64;

macro_rules! pool_arr {
    ($Arr:ident, $Ptr:ident) => {
        /// An `SbxPtr<T>` and a length, together: `len` elements of `T` in
        /// checkpointed pool memory.
        ///
        /// `Copy`, `#[repr(C)]`, and two words wide, so one fits in a struct
        /// that goes into a checkpoint or across to another binary. Equality
        /// and hashing compare the *address and length*, never the bytes: two
        /// arrays holding identical contents at different addresses are not
        /// equal.
        ///
        /// `as_slice`/`as_mut_slice` are safe and unchecked — they trust the
        /// length the array was built with.
        #[repr(C)]
        pub struct $Arr<T: SandboxSafe> {
            ptr: $Ptr<T>,
            len: usize,
        }

        unsafe impl<T: SandboxSafe> Send for $Arr<T> {}
        unsafe impl<T: SandboxSafe> Sync for $Arr<T> {}

        impl<T: SandboxSafe> Copy for $Arr<T> {}
        impl<T: SandboxSafe> Clone for $Arr<T> {
            fn clone(&self) -> Self {
                *self
            }
        }

        impl<T: SandboxSafe> $Arr<T> {
            /// Pair a pointer with the number of elements behind it.
            ///
            /// # Safety
            ///
            /// `ptr .. ptr + len * size_of::<T>()` must lie inside one
            /// allocation, live for as long as the array is used.
            pub unsafe fn from_raw_parts(ptr: $Ptr<T>, len: usize) -> Self {
                Self { ptr, len }
            }

            /// The address of the first element.
            pub fn as_ptr(&self) -> $Ptr<T> {
                self.ptr
            }

            /// Elements, not bytes.
            pub fn len(&self) -> usize {
                self.len
            }

            /// True when the length is 0, whatever the address is.
            pub fn is_empty(&self) -> bool {
                self.len == 0
            }

            /// The elements as a slice.
            pub fn as_slice(&self) -> &[T] {
                unsafe { core::slice::from_raw_parts(self.ptr.as_raw_ptr(), self.len) }
            }

            /// The elements as a mutable slice.
            pub fn as_mut_slice(&mut self) -> &mut [T] {
                unsafe { core::slice::from_raw_parts_mut(self.ptr.as_raw_ptr(), self.len) }
            }

            /// A narrower view of the same memory — nothing is copied, and a
            /// write through the result is a write through the original.
            ///
            /// # Panics
            ///
            /// If `range.end` is past the array's length.
            ///
            /// `range.start` is not checked against `range.end`. A reversed
            /// range subtracts past zero — a panic where overflow checks are
            /// on, an enormous length where they are off — so screen a range
            /// that came from outside before passing it.
            pub fn subslice(&self, range: Range<usize>) -> Self {
                assert!(
                    range.end <= self.len,
                    "{}::subslice: {range:?} out of bounds (len={})",
                    stringify!($Arr),
                    self.len
                );
                Self {
                    ptr: self.ptr.byte_add(range.start * core::mem::size_of::<T>()),
                    len: range.end - range.start,
                }
            }
        }

        #[cfg(feature = "component")]
        impl $Arr<u8> {
            /// Fill this array from `src`.
            ///
            /// # Panics
            ///
            /// If `src.len()` is not exactly the array's length. There is no
            /// partial copy and no truncation.
            pub fn copy_from_slice(&self, src: &[u8]) {
                assert_eq!(
                    src.len(),
                    self.len,
                    "{}<u8>::copy_from_slice: length mismatch",
                    stringify!($Arr)
                );
                let dst =
                    unsafe { core::slice::from_raw_parts_mut(self.ptr.as_raw_ptr(), self.len) };
                simd_memcpy(dst, src);
            }

            /// Read this array out into `dst`.
            ///
            /// # Panics
            ///
            /// If `dst.len()` is not exactly the array's length.
            pub fn copy_to_slice(&self, dst: &mut [u8]) {
                assert_eq!(
                    dst.len(),
                    self.len,
                    "{}<u8>::copy_to_slice: length mismatch",
                    stringify!($Arr)
                );
                let src = unsafe { core::slice::from_raw_parts(self.ptr.as_raw_ptr(), self.len) };
                simd_memcpy(dst, src);
            }
        }

        impl<T: SandboxSafe> fmt::Debug for $Arr<T> {
            fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
                write!(f, "{}({:#x}, len={})", stringify!($Arr), self.ptr.to_u64(), self.len)
            }
        }

        impl<T: SandboxSafe> PartialEq for $Arr<T> {
            fn eq(&self, other: &Self) -> bool {
                self.ptr == other.ptr && self.len == other.len
            }
        }
        impl<T: SandboxSafe> Eq for $Arr<T> {}

        impl<T: SandboxSafe> Hash for $Arr<T> {
            fn hash<H: Hasher>(&self, state: &mut H) {
                self.ptr.hash(state);
                self.len.hash(state);
            }
        }
    };
}

pool_arr!(SbxArray, SbxPtr);

#[cfg(feature = "component")]
macro_rules! simd_load {
    ($src:expr, $i:literal) => {{
        // SAFETY: caller ensures $src..$src + ($i+1)*MEMCPY_LANES is in-bounds.
        let chunk = unsafe { from_raw_parts($src.add($i * MEMCPY_LANES), MEMCPY_LANES) };
        Simd::<u8, MEMCPY_LANES>::from_slice(chunk)
    }};
}

#[cfg(feature = "component")]
macro_rules! simd_store {
    ($dst:expr, $i:literal, $v:expr) => {{
        // SAFETY: caller ensures $dst..$dst + ($i+1)*MEMCPY_LANES is in-bounds.
        let chunk = unsafe { from_raw_parts_mut($dst.add($i * MEMCPY_LANES), MEMCPY_LANES) };
        $v.copy_to_slice(chunk);
    }};
}

#[cfg(feature = "component")]
macro_rules! simd_unrolled_copy {
    (1, $src:ident, $dst:ident, $chunks:ident) => {{
        let v0 = simd_load!($src, 0);
        simd_store!($dst, 0, v0);
        // SAFETY: match guard ensures $chunks >= 1, so the just-read/written
        // MEMCPY_LANES bytes were in-bounds and the advanced pointers remain
        // within the loop's running invariant.
        $src = unsafe { $src.add(MEMCPY_LANES) };
        $dst = unsafe { $dst.add(MEMCPY_LANES) };
        $chunks -= 1;
    }};
    (2, $src:ident, $dst:ident, $chunks:ident) => {{
        let v0 = simd_load!($src, 0);
        let v1 = simd_load!($src, 1);
        simd_store!($dst, 0, v0);
        simd_store!($dst, 1, v1);
        // SAFETY: match guard ensures $chunks >= 2.
        $src = unsafe { $src.add(2 * MEMCPY_LANES) };
        $dst = unsafe { $dst.add(2 * MEMCPY_LANES) };
        $chunks -= 2;
    }};
    (4, $src:ident, $dst:ident, $chunks:ident) => {{
        let v0 = simd_load!($src, 0);
        let v1 = simd_load!($src, 1);
        let v2 = simd_load!($src, 2);
        let v3 = simd_load!($src, 3);
        simd_store!($dst, 0, v0);
        simd_store!($dst, 1, v1);
        simd_store!($dst, 2, v2);
        simd_store!($dst, 3, v3);
        // SAFETY: match guard ensures $chunks >= 4.
        $src = unsafe { $src.add(4 * MEMCPY_LANES) };
        $dst = unsafe { $dst.add(4 * MEMCPY_LANES) };
        $chunks -= 4;
    }};
    (8, $src:ident, $dst:ident, $chunks:ident) => {{
        let v0 = simd_load!($src, 0);
        let v1 = simd_load!($src, 1);
        let v2 = simd_load!($src, 2);
        let v3 = simd_load!($src, 3);
        let v4 = simd_load!($src, 4);
        let v5 = simd_load!($src, 5);
        let v6 = simd_load!($src, 6);
        let v7 = simd_load!($src, 7);
        simd_store!($dst, 0, v0);
        simd_store!($dst, 1, v1);
        simd_store!($dst, 2, v2);
        simd_store!($dst, 3, v3);
        simd_store!($dst, 4, v4);
        simd_store!($dst, 5, v5);
        simd_store!($dst, 6, v6);
        simd_store!($dst, 7, v7);
        // SAFETY: caller ensures $chunks >= 8.
        $src = unsafe { $src.add(8 * MEMCPY_LANES) };
        $dst = unsafe { $dst.add(8 * MEMCPY_LANES) };
        $chunks -= 8;
    }};
}

/// Copy `src` over `dst`, vectorized: 64-byte SIMD steps unrolled eight, four,
/// two and one at a time, then a scalar tail.
///
/// The two slices must not overlap.
///
/// # Panics
///
/// If the two lengths differ.
#[cfg(feature = "component")]
#[inline]
#[allow(unused_assignments)] // unrolled_copy macros write back chunks/src/dst on the final branch
pub fn simd_memcpy(dst: &mut [u8], src: &[u8]) {
    assert_eq!(dst.len(), src.len(), "simd_memcpy: length mismatch");
    let len = src.len();
    let tail = len % MEMCPY_LANES;
    let mut chunks = len / MEMCPY_LANES;
    let mut src = src.as_ptr();
    let mut dst = dst.as_mut_ptr();

    while chunks >= 8 {
        simd_unrolled_copy!(8, src, dst, chunks);
    }
    if chunks >= 4 {
        simd_unrolled_copy!(4, src, dst, chunks);
    }
    if chunks >= 2 {
        simd_unrolled_copy!(2, src, dst, chunks);
    }
    if chunks >= 1 {
        simd_unrolled_copy!(1, src, dst, chunks);
    }
    if tail != 0 {
        // SAFETY: tail < MEMCPY_LANES bytes remain in both src and dst at this
        // offset; the loop above advanced src and dst to (len - tail).
        unsafe { copy_nonoverlapping(src, dst, tail) };
    }
}