Skip to main content

kh_runtime/
process.rs

1//! Process-wide translator state for the single guest-process model.
2//!
3//! Hot paths avoid the process [`RwLock`]:
4//! - FD map: lock-free atomics ([`fd_get`] / [`fd_alloc`] / [`fd_take`])
5//! - bottle root: narrow [`Arc`] slot ([`with_bottle_root`])
6//! - `bsdthread_register`: atomic pointer snapshot ([`bsdthread_reg`])
7//!
8//! Soft signals and directory streams still use [`with_mut`] / [`with_ref`].
9
10use std::collections::HashMap;
11use std::os::fd::RawFd;
12use std::path::{Path, PathBuf};
13use std::sync::atomic::{AtomicI32, AtomicU64, Ordering};
14use std::sync::{Arc, OnceLock, RwLock};
15
16use crate::host;
17
18/// Process-wide syscall counter (hot path: no process-state lock).
19static SYSCALL_COUNT: AtomicU64 = AtomicU64::new(0);
20/// Cap for [`SYSCALL_COUNT`]; updated by [`reset_run`].
21static MAX_SYSCALLS: AtomicU64 = AtomicU64::new(256);
22
23/// Unreaped host children from guest `fork` (parent side only).
24///
25/// Used so `read` can emulate Darwin **blocking** notify-pipe waits after
26/// spawn while pipes themselves stay `O_NONBLOCK` for curl/c-ares.
27static LIVE_CHILDREN: AtomicU64 = AtomicU64::new(0);
28
29/// Max guest FD slots (stdio 0–2 + table). Keeps FDs under typical OPEN_MAX.
30const FD_SLOTS: usize = 1024;
31/// Empty slot in the lock-free FD map.
32const FD_EMPTY: i32 = -1;
33
34/// Guest → host FD map for **lookup** without the process `RwLock`.
35///
36/// Slots 0–2 are unused (stdio identity). Other slots: host fd ≥ 0, or [`FD_EMPTY`].
37/// Alloc/take update these atomics; dir streams still use the process lock.
38static FD_HOST: [AtomicI32; FD_SLOTS] = [const { AtomicI32::new(FD_EMPTY) }; FD_SLOTS];
39/// Hint for next free FD scan.
40static FD_NEXT: AtomicI32 = AtomicI32::new(3);
41
42/// Soft Darwin `sigaction` slot (handler + mask + flags).
43#[derive(Clone, Copy, Debug)]
44pub(crate) struct SoftSigAct {
45    pub handler: u64,
46    pub mask: u32,
47    pub flags: i32,
48}
49
50/// Values from Darwin `bsdthread_register` (libpthread start trampoline, etc.).
51///
52/// Extra fields are retained for future workq/TLS wiring even when unused today.
53#[derive(Clone, Copy, Debug, Default)]
54#[allow(dead_code)]
55pub(crate) struct BsdThreadReg {
56    /// Userland start trampoline (`_pthread_start`).
57    pub threadstart: u64,
58    /// Workqueue thread entry (unused in micro; stored for completeness).
59    pub wqthread: u64,
60    /// Registration flags from libpthread.
61    pub flags: u32,
62    /// Stack address hint (unused in micro).
63    pub stack_addr_hint: u64,
64    /// TSD offset within the pthread structure.
65    pub tsd_offset: u32,
66    /// Dispatch queue offset within the pthread structure.
67    pub dispatchqueue_offset: u32,
68}
69
70impl SoftSigAct {
71    pub(crate) const fn zero() -> Self {
72        Self {
73            handler: 0,
74            mask: 0,
75            flags: 0,
76        }
77    }
78}
79
80/// Marker so `ProcessState::reset_run` can clear the lock-free FD map.
81#[derive(Debug, Default)]
82struct FdTable;
83
84impl FdTable {
85    const fn new() -> Self {
86        Self
87    }
88
89    fn reset(&mut self) {
90        let _ = self;
91        reset_fd_map();
92    }
93}
94
95/// Resolve guest FD → host FD without taking the process lock (I/O hot path).
96#[must_use]
97#[inline]
98pub fn fd_get(gfd: i32) -> Option<RawFd> {
99    if gfd == 0 || gfd == 1 || gfd == 2 {
100        return Some(gfd);
101    }
102    if gfd < 0 {
103        return None;
104    }
105    let Ok(idx) = usize::try_from(gfd) else {
106        return None;
107    };
108    let slot = FD_HOST.get(idx)?;
109    let v = slot.load(Ordering::Acquire);
110    if v < 0 { None } else { Some(v) }
111}
112
113/// Removes a guest FD mapping and returns the host fd (lock-free).
114#[must_use]
115#[inline]
116pub fn fd_take(gfd: i32) -> Option<RawFd> {
117    if gfd <= 2 {
118        return None;
119    }
120    let Ok(idx) = usize::try_from(gfd) else {
121        return None;
122    };
123    let slot = FD_HOST.get(idx)?;
124    let v = slot.swap(FD_EMPTY, Ordering::AcqRel);
125    if v < 0 { None } else { Some(v) }
126}
127
128/// Installs `host_fd` into a **specific** guest FD slot (for `dup2`).
129///
130/// Closes any previous host mapping at `gfd` (except stdio 0–2 identity).
131/// Returns `false` if `gfd` is out of range.
132#[must_use]
133#[inline]
134pub fn fd_install(gfd: i32, host_fd: RawFd) -> bool {
135    if host_fd < 0 || gfd < 3 {
136        return false;
137    }
138    let Ok(idx) = usize::try_from(gfd) else {
139        return false;
140    };
141    let Some(slot) = FD_HOST.get(idx) else {
142        return false;
143    };
144    let prev = slot.swap(host_fd, Ordering::AcqRel);
145    if prev >= 0 && prev != host_fd {
146        host::close_fd(prev);
147    }
148    true
149}
150
151/// Allocates a guest FD slot for `host_fd` (lock-free CAS scan).
152#[must_use]
153#[inline]
154pub fn fd_alloc(host_fd: RawFd) -> Option<i32> {
155    if host_fd < 0 {
156        return None;
157    }
158    let start = usize::try_from(FD_NEXT.load(Ordering::Relaxed).max(3)).unwrap_or(3);
159    for idx in start..FD_SLOTS {
160        if try_claim_slot(idx, host_fd) {
161            let gfd = i32::try_from(idx).ok()?;
162            FD_NEXT.store(gfd.saturating_add(1), Ordering::Relaxed);
163            return Some(gfd);
164        }
165    }
166    for idx in 3..start.min(FD_SLOTS) {
167        if try_claim_slot(idx, host_fd) {
168            let gfd = i32::try_from(idx).ok()?;
169            FD_NEXT.store(gfd.saturating_add(1), Ordering::Relaxed);
170            return Some(gfd);
171        }
172    }
173    None
174}
175
176/// Bottle root published for path translation (set once per run; rare updates).
177static BOTTLE_ROOT: RwLock<Option<Arc<PathBuf>>> = RwLock::new(None);
178
179/// Open `O_DIRECTORY` fd for the bottle root (`-1` = none).
180///
181/// Hot path: absolute guest paths use `openat`/`fstatat` against this fd
182/// instead of building `{root}/{rel}` PathBuf + `open` from `/` each call (B1).
183static BOTTLE_DIRFD: AtomicI32 = AtomicI32::new(-1);
184
185/// `bsdthread_register` snapshot (narrow lock; not the full process state).
186static BSDTHREAD_REG: RwLock<Option<BsdThreadReg>> = RwLock::new(None);
187
188fn try_claim_slot(idx: usize, host_fd: RawFd) -> bool {
189    let Some(slot) = FD_HOST.get(idx) else {
190        return false;
191    };
192    slot.compare_exchange(FD_EMPTY, host_fd, Ordering::AcqRel, Ordering::Relaxed)
193        .is_ok()
194}
195
196fn reset_fd_map() {
197    for (i, slot) in FD_HOST.iter().enumerate() {
198        let prev = slot.swap(FD_EMPTY, Ordering::AcqRel);
199        if i > 2 && prev >= 0 {
200            host::close_fd(prev);
201        }
202    }
203    FD_NEXT.store(3, Ordering::Relaxed);
204}
205
206/// Owned process state for one guest (or unit-test isolation via reset).
207///
208/// Bottle root and `bsdthread_register` live in separate process-wide slots so
209/// open/create hot paths do not take this lock.
210#[derive(Debug)]
211pub struct ProcessState {
212    fds: FdTable,
213    /// Guest FD → directory stream (for `readdir` host helper).
214    dir_streams: HashMap<i32, host::HostDir>,
215    sig_mask: u32,
216    sigactions: [SoftSigAct; 32],
217}
218
219impl ProcessState {
220    /// Fresh process state with default syscall limit.
221    #[must_use]
222    pub fn new() -> Self {
223        Self {
224            fds: FdTable::new(),
225            dir_streams: HashMap::new(),
226            sig_mask: 0,
227            sigactions: [SoftSigAct::zero(); 32],
228        }
229    }
230
231    /// Resets FD table, soft signals, thread reg, and counters. Preserves bottle root.
232    pub fn reset_run(&mut self, max_syscalls: usize) {
233        self.dir_streams.clear();
234        self.fds.reset();
235        self.sig_mask = 0;
236        self.sigactions = [SoftSigAct::zero(); 32];
237        clear_bsdthread_reg();
238        let max = u64::try_from(max_syscalls).unwrap_or(256);
239        MAX_SYSCALLS.store(max, Ordering::Relaxed);
240        SYSCALL_COUNT.store(0, Ordering::Relaxed);
241        LIVE_CHILDREN.store(0, Ordering::Relaxed);
242        crate::thread::reset_thread_runtime();
243    }
244
245    /// Closes any directory stream associated with `gfd` (call before FD free).
246    pub(crate) fn close_dir_stream(&mut self, gfd: i32) {
247        drop(self.dir_streams.remove(&gfd));
248    }
249
250    /// Returns the next directory entry for `gfd`, opening a stream on first use.
251    ///
252    /// `None` means end-of-directory (or empty). `Err(errno)` on failure.
253    pub(crate) fn readdir_next(&mut self, gfd: i32) -> Result<Option<(Vec<u8>, u8)>, i64> {
254        let Some(host_fd) = fd_get(gfd) else {
255            return Err(9); // EBADF
256        };
257
258        if let std::collections::hash_map::Entry::Vacant(e) = self.dir_streams.entry(gfd) {
259            match host::HostDir::open_dup(host_fd) {
260                Ok(dir) => {
261                    e.insert(dir);
262                }
263                Err(err) => return Err(i64::from(err)),
264            }
265        }
266
267        let Some(stream) = self.dir_streams.get_mut(&gfd) else {
268            return Err(9);
269        };
270        Ok(stream.read_next())
271    }
272
273    #[must_use]
274    pub(crate) fn sig_mask(&self) -> u32 {
275        self.sig_mask
276    }
277
278    pub(crate) fn set_sig_mask(&mut self, mask: u32) {
279        self.sig_mask = mask;
280    }
281
282    #[must_use]
283    pub(crate) fn sigaction(&self, sig: usize) -> Option<SoftSigAct> {
284        self.sigactions.get(sig).copied()
285    }
286
287    pub(crate) fn set_sigaction(&mut self, sig: usize, act: SoftSigAct) -> bool {
288        if let Some(slot) = self.sigactions.get_mut(sig) {
289            *slot = act;
290            true
291        } else {
292            false
293        }
294    }
295}
296
297impl Default for ProcessState {
298    fn default() -> Self {
299        Self::new()
300    }
301}
302
303/// Parent observed a successful `fork` (child pid > 0).
304#[inline]
305pub fn child_born() {
306    LIVE_CHILDREN.fetch_add(1, Ordering::Relaxed);
307}
308
309/// Parent reaped at least one child via `waitpid`/`wait4`.
310#[inline]
311pub fn child_reaped() {
312    let _ = LIVE_CHILDREN.fetch_update(Ordering::Relaxed, Ordering::Relaxed, |n| {
313        Some(n.saturating_sub(1))
314    });
315}
316
317/// Number of unreaped host children (approximate; for pipe blocking heuristics).
318#[must_use]
319#[inline]
320pub fn live_children() -> u64 {
321    LIVE_CHILDREN.load(Ordering::Relaxed)
322}
323
324/// Bumps the process-wide syscall counter without taking the process lock.
325///
326/// Returns `true` when the configured max has been exceeded.
327#[must_use]
328pub fn tick_syscall() -> bool {
329    let n = SYSCALL_COUNT.fetch_add(1, Ordering::Relaxed);
330    n >= MAX_SYSCALLS.load(Ordering::Relaxed)
331}
332
333fn active_lock() -> &'static RwLock<ProcessState> {
334    static ACTIVE: OnceLock<RwLock<ProcessState>> = OnceLock::new();
335    ACTIVE.get_or_init(|| RwLock::new(ProcessState::new()))
336}
337
338/// Exclusive access to the active process state.
339pub fn with_mut<R>(f: impl FnOnce(&mut ProcessState) -> R) -> R {
340    match active_lock().write() {
341        Ok(mut guard) => f(&mut guard),
342        Err(poisoned) => f(&mut poisoned.into_inner()),
343    }
344}
345
346/// Shared access to the active process state (concurrent FD lookups, etc.).
347pub fn with_ref<R>(f: impl FnOnce(&ProcessState) -> R) -> R {
348    match active_lock().read() {
349        Ok(guard) => f(&guard),
350        Err(poisoned) => f(&poisoned.into_inner()),
351    }
352}
353
354/// Resets FD/signals/counters for a new guest run (keeps bottle root).
355pub fn reset_run(max_syscalls: usize) {
356    with_mut(|p| p.reset_run(max_syscalls));
357}
358
359/// Configures the bottle root used by path-taking syscalls.
360///
361/// Also opens/replaces the process-wide bottle directory fd for B1 `openat`.
362pub fn set_bottle_root(root: Option<PathBuf>) {
363    let new_fd = root.as_ref().map_or(-1, |p| open_bottle_dirfd(p).unwrap_or(-1));
364    let old_fd = BOTTLE_DIRFD.swap(new_fd, Ordering::AcqRel);
365    if old_fd >= 0 {
366        host::close_fd(old_fd);
367    }
368
369    let next = root.map(Arc::new);
370    match BOTTLE_ROOT.write() {
371        Ok(mut guard) => {
372            *guard = next;
373        }
374        Err(poisoned) => {
375            *poisoned.into_inner() = next;
376        }
377    }
378}
379
380/// Clone of the configured bottle root, if any.
381#[must_use]
382pub fn bottle_root() -> Option<PathBuf> {
383    with_bottle_root(|p| p.map(Path::to_path_buf))
384}
385
386/// Borrow the bottle root without cloning (hot path for path translation).
387///
388/// Uses a **narrow** bottle-root lock (not the full process state).
389pub fn with_bottle_root<R>(f: impl FnOnce(Option<&Path>) -> R) -> R {
390    match BOTTLE_ROOT.read() {
391        Ok(guard) => f(guard.as_ref().map(|a| a.as_path())),
392        Err(poisoned) => f(poisoned.into_inner().as_ref().map(|a| a.as_path())),
393    }
394}
395
396/// Process-wide bottle root directory fd for `openat`/`fstatat` (B1).
397///
398/// `None` when no bottle is configured or the directory could not be opened.
399#[must_use]
400pub fn bottle_dirfd() -> Option<RawFd> {
401    let fd = BOTTLE_DIRFD.load(Ordering::Acquire);
402    if fd >= 0 { Some(fd) } else { None }
403}
404
405/// Open `root` as `O_RDONLY|O_DIRECTORY|O_CLOEXEC` for hot-path `openat`.
406fn open_bottle_dirfd(root: &Path) -> Option<RawFd> {
407    let c = std::ffi::CString::new(root.as_os_str().as_encoded_bytes()).ok()?;
408    host::open_directory(&c)
409}
410
411/// Stores `bsdthread_register` metadata for subsequent `bsdthread_create`.
412pub(crate) fn set_bsdthread_reg(reg: BsdThreadReg) {
413    match BSDTHREAD_REG.write() {
414        Ok(mut guard) => {
415            *guard = Some(reg);
416        }
417        Err(poisoned) => {
418            *poisoned.into_inner() = Some(reg);
419        }
420    }
421}
422
423/// Snapshot of the last `bsdthread_register` (narrow lock, copy-out).
424#[must_use]
425pub(crate) fn bsdthread_reg() -> Option<BsdThreadReg> {
426    match BSDTHREAD_REG.read() {
427        Ok(guard) => *guard,
428        Err(poisoned) => *poisoned.into_inner(),
429    }
430}
431
432fn clear_bsdthread_reg() {
433    match BSDTHREAD_REG.write() {
434        Ok(mut guard) => {
435            *guard = None;
436        }
437        Err(poisoned) => {
438            *poisoned.into_inner() = None;
439        }
440    }
441}
442
443/// Serializes tests that mutate process-wide state (address space + process).
444#[cfg(test)]
445pub(crate) fn test_lock() -> std::sync::MutexGuard<'static, ()> {
446    use std::sync::Mutex;
447    static LOCK: Mutex<()> = Mutex::new(());
448    LOCK.lock()
449        .unwrap_or_else(std::sync::PoisonError::into_inner)
450}