kh-runtime 0.1.2

Kakehashi native ARM64 execution context, memory layout, traps, and bottle
Documentation
//! Process-wide translator state for the single guest-process model.
//!
//! Hot paths avoid the process `RwLock`:
//! - FD table is lock-free atomics ([`fd_get`] / [`fd_alloc`] / [`fd_take`])
//! - Bottle root is a separate `RwLock` (path translate never takes process write)
//! - Directory streams use a dedicated mutex (readdir never blocks open/stat)

use std::collections::HashMap;
use std::os::fd::RawFd;
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicI32, AtomicU64, Ordering};
use std::sync::{Mutex, OnceLock, RwLock};

use crate::host;

/// Process-wide syscall counter (hot path: no process-state lock).
static SYSCALL_COUNT: AtomicU64 = AtomicU64::new(0);
/// Cap for [`SYSCALL_COUNT`]; updated by [`reset_run`].
static MAX_SYSCALLS: AtomicU64 = AtomicU64::new(256);

/// Max guest FD slots (stdio 0–2 + table). Keeps FDs under typical OPEN_MAX.
const FD_SLOTS: usize = 1024;
/// Empty slot in the lock-free FD map.
const FD_EMPTY: i32 = -1;

/// Guest → host FD map for **lookup** without the process `RwLock`.
///
/// Slots 0–2 are unused (stdio identity). Other slots: host fd ≥ 0, or [`FD_EMPTY`].
static FD_HOST: [AtomicI32; FD_SLOTS] = [const { AtomicI32::new(FD_EMPTY) }; FD_SLOTS];
/// Hint for next free FD scan.
static FD_NEXT: AtomicI32 = AtomicI32::new(3);

/// Soft Darwin `sigaction` slot (handler + mask + flags).
#[derive(Clone, Copy, Debug)]
pub(crate) struct SoftSigAct {
    pub handler: u64,
    pub mask: u32,
    pub flags: i32,
}

/// Values from Darwin `bsdthread_register` (libpthread start trampoline, etc.).
///
/// Extra fields are retained for future workq/TLS wiring even when unused today.
#[derive(Clone, Copy, Debug, Default)]
#[allow(dead_code)]
pub(crate) struct BsdThreadReg {
    /// Userland start trampoline (`_pthread_start`).
    pub threadstart: u64,
    /// Workqueue thread entry (unused in micro; stored for completeness).
    pub wqthread: u64,
    /// Registration flags from libpthread.
    pub flags: u32,
    /// Stack address hint (unused in micro).
    pub stack_addr_hint: u64,
    /// TSD offset within the pthread structure.
    pub tsd_offset: u32,
    /// Dispatch queue offset within the pthread structure.
    pub dispatchqueue_offset: u32,
}

impl SoftSigAct {
    pub(crate) const fn zero() -> Self {
        Self {
            handler: 0,
            mask: 0,
            flags: 0,
        }
    }
}

/// Resolve guest FD → host FD without taking the process lock (I/O hot path).
#[must_use]
#[inline]
pub fn fd_get(gfd: i32) -> Option<RawFd> {
    if gfd == 0 || gfd == 1 || gfd == 2 {
        return Some(gfd);
    }
    if gfd < 0 {
        return None;
    }
    let Ok(idx) = usize::try_from(gfd) else {
        return None;
    };
    let slot = FD_HOST.get(idx)?;
    let v = slot.load(Ordering::Acquire);
    if v < 0 { None } else { Some(v) }
}

/// Allocates a guest FD for `host_fd` without the process lock.
#[must_use]
#[inline]
pub fn fd_alloc(host_fd: RawFd) -> Option<i32> {
    if host_fd < 0 {
        return None;
    }
    let start = usize::try_from(FD_NEXT.load(Ordering::Relaxed).max(3)).unwrap_or(3);
    for idx in start..FD_SLOTS {
        if try_claim_slot(idx, host_fd) {
            let gfd = i32::try_from(idx).ok()?;
            FD_NEXT.store(gfd.saturating_add(1), Ordering::Relaxed);
            return Some(gfd);
        }
    }
    for idx in 3..start.min(FD_SLOTS) {
        if try_claim_slot(idx, host_fd) {
            let gfd = i32::try_from(idx).ok()?;
            FD_NEXT.store(gfd.saturating_add(1), Ordering::Relaxed);
            return Some(gfd);
        }
    }
    None
}

/// Removes a guest FD mapping and returns the host FD (lock-free).
#[must_use]
#[inline]
pub fn fd_take(gfd: i32) -> Option<RawFd> {
    if gfd <= 2 {
        return None;
    }
    let Ok(idx) = usize::try_from(gfd) else {
        return None;
    };
    let slot = FD_HOST.get(idx)?;
    let v = slot.swap(FD_EMPTY, Ordering::AcqRel);
    if v < 0 { None } else { Some(v) }
}

fn try_claim_slot(idx: usize, host_fd: RawFd) -> bool {
    let Some(slot) = FD_HOST.get(idx) else {
        return false;
    };
    slot.compare_exchange(FD_EMPTY, host_fd, Ordering::AcqRel, Ordering::Relaxed)
        .is_ok()
}

fn reset_fd_map() {
    for (i, slot) in FD_HOST.iter().enumerate() {
        let prev = slot.swap(FD_EMPTY, Ordering::AcqRel);
        if i > 2 && prev >= 0 {
            host::close_fd(prev);
        }
    }
    FD_NEXT.store(3, Ordering::Relaxed);
}

// ── bottle root (separate from process lock) ────────────────────────────────

fn bottle_root_lock() -> &'static RwLock<Option<PathBuf>> {
    static ROOT: OnceLock<RwLock<Option<PathBuf>>> = OnceLock::new();
    ROOT.get_or_init(|| RwLock::new(None))
}

// ── directory streams (separate mutex; readdir ≠ open contention) ───────────

fn dir_streams_lock() -> &'static Mutex<HashMap<i32, host::HostDir>> {
    static DIRS: OnceLock<Mutex<HashMap<i32, host::HostDir>>> = OnceLock::new();
    DIRS.get_or_init(|| Mutex::new(HashMap::new()))
}

/// Closes any directory stream associated with `gfd` (call before FD free).
pub fn close_dir_stream(gfd: i32) {
    if let Ok(mut map) = dir_streams_lock().lock() {
        drop(map.remove(&gfd));
    } else if let Err(poisoned) = dir_streams_lock().lock() {
        drop(poisoned.into_inner().remove(&gfd));
    }
}

/// Next directory entry for `gfd`, writing the name into `name_out` (NUL-terminated).
///
/// Returns `Ok(Some(d_type))` when an entry was written, `Ok(None)` at EOF.
pub fn readdir_next_into(gfd: i32, name_out: &mut [u8]) -> Result<Option<u8>, i64> {
    let Some(host_fd) = fd_get(gfd) else {
        return Err(9); // EBADF
    };

    let mut map = match dir_streams_lock().lock() {
        Ok(g) => g,
        Err(p) => p.into_inner(),
    };

    if let std::collections::hash_map::Entry::Vacant(e) = map.entry(gfd) {
        match host::HostDir::open_dup(host_fd) {
            Ok(dir) => {
                e.insert(dir);
            }
            Err(err) => return Err(i64::from(err)),
        }
    }

    let Some(stream) = map.get_mut(&gfd) else {
        return Err(9);
    };
    match stream.read_next_into(name_out) {
        Some(d_type) => Ok(Some(d_type)),
        None => Ok(None),
    }
}

/// Owned process state for one guest (or unit-test isolation via reset).
#[derive(Debug)]
pub struct ProcessState {
    sig_mask: u32,
    sigactions: [SoftSigAct; 32],
    bsdthread: Option<BsdThreadReg>,
}

impl ProcessState {
    /// Fresh process state with default syscall limit.
    #[must_use]
    pub fn new() -> Self {
        Self {
            sig_mask: 0,
            sigactions: [SoftSigAct::zero(); 32],
            bsdthread: None,
        }
    }

    /// Resets FD table, soft signals, thread reg, and counters. Preserves bottle root.
    pub fn reset_run(&mut self, max_syscalls: usize) {
        // Drop all directory streams before closing FDs.
        if let Ok(mut map) = dir_streams_lock().lock() {
            map.clear();
        } else if let Err(poisoned) = dir_streams_lock().lock() {
            poisoned.into_inner().clear();
        }
        reset_fd_map();
        self.sig_mask = 0;
        self.sigactions = [SoftSigAct::zero(); 32];
        self.bsdthread = None;
        let max = u64::try_from(max_syscalls).unwrap_or(256);
        MAX_SYSCALLS.store(max, Ordering::Relaxed);
        SYSCALL_COUNT.store(0, Ordering::Relaxed);
        crate::thread::reset_thread_runtime();
    }

    #[must_use]
    pub(crate) fn bsdthread(&self) -> Option<BsdThreadReg> {
        self.bsdthread
    }

    pub(crate) fn set_bsdthread(&mut self, reg: BsdThreadReg) {
        self.bsdthread = Some(reg);
    }

    #[must_use]
    pub(crate) fn sig_mask(&self) -> u32 {
        self.sig_mask
    }

    pub(crate) fn set_sig_mask(&mut self, mask: u32) {
        self.sig_mask = mask;
    }

    #[must_use]
    pub(crate) fn sigaction(&self, sig: usize) -> Option<SoftSigAct> {
        self.sigactions.get(sig).copied()
    }

    pub(crate) fn set_sigaction(&mut self, sig: usize, act: SoftSigAct) -> bool {
        if let Some(slot) = self.sigactions.get_mut(sig) {
            *slot = act;
            true
        } else {
            false
        }
    }
}

impl Default for ProcessState {
    fn default() -> Self {
        Self::new()
    }
}

/// Bumps the process-wide syscall counter without taking the process lock.
///
/// Returns `true` when the configured max has been exceeded.
#[must_use]
pub fn tick_syscall() -> bool {
    let n = SYSCALL_COUNT.fetch_add(1, Ordering::Relaxed);
    n >= MAX_SYSCALLS.load(Ordering::Relaxed)
}

fn active_lock() -> &'static RwLock<ProcessState> {
    static ACTIVE: OnceLock<RwLock<ProcessState>> = OnceLock::new();
    ACTIVE.get_or_init(|| RwLock::new(ProcessState::new()))
}

/// Exclusive access to the active process state.
pub fn with_mut<R>(f: impl FnOnce(&mut ProcessState) -> R) -> R {
    match active_lock().write() {
        Ok(mut guard) => f(&mut guard),
        Err(poisoned) => f(&mut poisoned.into_inner()),
    }
}

/// Shared access to the active process state.
pub fn with_ref<R>(f: impl FnOnce(&ProcessState) -> R) -> R {
    match active_lock().read() {
        Ok(guard) => f(&guard),
        Err(poisoned) => f(&poisoned.into_inner()),
    }
}

/// Resets FD/signals/counters for a new guest run (keeps bottle root).
pub fn reset_run(max_syscalls: usize) {
    with_mut(|p| p.reset_run(max_syscalls));
}

/// Configures the bottle root used by path-taking syscalls.
pub fn set_bottle_root(root: Option<PathBuf>) {
    match bottle_root_lock().write() {
        Ok(mut g) => *g = root,
        Err(p) => *p.into_inner() = root,
    }
}

/// Clone of the configured bottle root, if any.
#[must_use]
pub fn bottle_root() -> Option<PathBuf> {
    match bottle_root_lock().read() {
        Ok(g) => g.clone(),
        Err(p) => p.into_inner().clone(),
    }
}

/// Borrow the bottle root without cloning (hot path for path translation).
pub fn with_bottle_root<R>(f: impl FnOnce(Option<&Path>) -> R) -> R {
    match bottle_root_lock().read() {
        Ok(g) => f(g.as_deref()),
        Err(p) => f(p.into_inner().as_deref()),
    }
}

/// Serializes tests that mutate process-wide state (address space + process).
#[cfg(test)]
pub(crate) fn test_lock() -> std::sync::MutexGuard<'static, ()> {
    use std::sync::Mutex as StdMutex;
    static LOCK: StdMutex<()> = StdMutex::new(());
    LOCK.lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner)
}