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, AtomicU8, 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/// Secondary signal for blocking I/O waits; primary control is
26/// [`fd_guest_nonblock`] (guest `O_NONBLOCK` flag).
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/// Guest-visible `O_NONBLOCK` per FD slot (including stdio 0–2).
40///
41/// Host pipes/sockets are often forced non-blocking for curl multi; Darwin
42/// guests still expect **blocking** semantics until they `fcntl(F_SETFL)`.
43/// I/O emulates blocking waits when this bit is clear.
44static FD_GUEST_NB: [AtomicU8; FD_SLOTS] = [const { AtomicU8::new(0) }; FD_SLOTS];
45/// Guest FD has a host-side TLS session ([`crate::tls_fd`]).
46///
47/// Lock-free hot-path check so ordinary `read`/`write` skip the TLS HashMap.
48static FD_TLS: [AtomicU8; FD_SLOTS] = [const { AtomicU8::new(0) }; FD_SLOTS];
49/// Hint for next free FD scan.
50static FD_NEXT: AtomicI32 = AtomicI32::new(3);
51/// Guest has `close`'d stdio slots 0/1/2 (bit0=stdin, bit1=stdout, bit2=stderr).
52///
53/// Stdio is identity-mapped to host 0/1/2, so a soft no-op `close` left the host
54/// pipe open. Apple `git fetch-pack --stateless-rpc` closes stdout **before**
55/// printing the fetched-ref list; with a no-op close those lines reach the
56/// remote-curl helper and surface as hundreds of
57/// `https unexpectedly said: '<sha> refs/…'` warnings after a successful clone.
58static STDIO_CLOSED: AtomicU8 = AtomicU8::new(0);
59
60/// Soft Darwin `sigaction` slot (handler + mask + flags).
61#[derive(Clone, Copy, Debug)]
62pub(crate) struct SoftSigAct {
63    pub handler: u64,
64    pub mask: u32,
65    pub flags: i32,
66}
67
68/// Values from Darwin `bsdthread_register` (libpthread start trampoline, etc.).
69///
70/// Extra fields are retained for future workq/TLS wiring even when unused today.
71#[derive(Clone, Copy, Debug, Default)]
72#[allow(dead_code)]
73pub(crate) struct BsdThreadReg {
74    /// Userland start trampoline (`_pthread_start`).
75    pub threadstart: u64,
76    /// Workqueue thread entry (unused in micro; stored for completeness).
77    pub wqthread: u64,
78    /// Registration flags from libpthread.
79    pub flags: u32,
80    /// Stack address hint (unused in micro).
81    pub stack_addr_hint: u64,
82    /// TSD offset within the pthread structure.
83    pub tsd_offset: u32,
84    /// Dispatch queue offset within the pthread structure.
85    pub dispatchqueue_offset: u32,
86}
87
88impl SoftSigAct {
89    pub(crate) const fn zero() -> Self {
90        Self {
91            handler: 0,
92            mask: 0,
93            flags: 0,
94        }
95    }
96}
97
98/// Marker so `ProcessState::reset_run` can clear the lock-free FD map.
99#[derive(Debug, Default)]
100struct FdTable;
101
102impl FdTable {
103    const fn new() -> Self {
104        Self
105    }
106
107    fn reset(&mut self) {
108        let _ = self;
109        reset_fd_map();
110    }
111}
112
113/// Resolve guest FD → host FD without taking the process lock (I/O hot path).
114#[must_use]
115#[inline]
116pub fn fd_get(gfd: i32) -> Option<RawFd> {
117    if gfd == 0 || gfd == 1 || gfd == 2 {
118        if stdio_is_closed(gfd) {
119            return None;
120        }
121        return Some(gfd);
122    }
123    if gfd < 0 {
124        return None;
125    }
126    let Ok(idx) = usize::try_from(gfd) else {
127        return None;
128    };
129    let slot = FD_HOST.get(idx)?;
130    let v = slot.load(Ordering::Acquire);
131    if v < 0 { None } else { Some(v) }
132}
133
134/// Removes a guest FD mapping and returns the host fd (lock-free).
135///
136/// For stdio 0–2: marks the slot closed and returns the host fd (identity) so
137/// the caller can `close` it — matching Darwin when `fetch-pack` drops stdout.
138#[must_use]
139#[inline]
140pub fn fd_take(gfd: i32) -> Option<RawFd> {
141    if gfd == 0 || gfd == 1 || gfd == 2 {
142        if stdio_is_closed(gfd) {
143            return None;
144        }
145        stdio_mark_closed(gfd);
146        return Some(gfd);
147    }
148    if gfd < 0 {
149        return None;
150    }
151    let Ok(idx) = usize::try_from(gfd) else {
152        return None;
153    };
154    let slot = FD_HOST.get(idx)?;
155    let v = slot.swap(FD_EMPTY, Ordering::AcqRel);
156    if let Some(t) = FD_TLS.get(idx) {
157        t.store(0, Ordering::Release);
158    }
159    if let Some(nb) = FD_GUEST_NB.get(idx) {
160        nb.store(0, Ordering::Release);
161    }
162    if v < 0 { None } else { Some(v) }
163}
164
165/// Bit for guest stdio FD in [`STDIO_CLOSED`] (`0→1`, `1→2`, `2→4`).
166#[inline]
167fn stdio_closed_bit(gfd: i32) -> Option<u8> {
168    match gfd {
169        0 => Some(1),
170        1 => Some(2),
171        2 => Some(4),
172        _ => None,
173    }
174}
175
176#[inline]
177fn stdio_is_closed(gfd: i32) -> bool {
178    let Some(bit) = stdio_closed_bit(gfd) else {
179        return false;
180    };
181    STDIO_CLOSED.load(Ordering::Acquire) & bit != 0
182}
183
184#[inline]
185fn stdio_mark_closed(gfd: i32) {
186    let Some(bit) = stdio_closed_bit(gfd) else {
187        return;
188    };
189    STDIO_CLOSED.fetch_or(bit, Ordering::AcqRel);
190}
191
192/// Clear the closed bit for a stdio slot (after successful `dup2` onto 0/1/2).
193#[inline]
194pub fn stdio_mark_open(gfd: i32) {
195    let Some(bit) = stdio_closed_bit(gfd) else {
196        return;
197    };
198    STDIO_CLOSED.fetch_and(!bit, Ordering::AcqRel);
199}
200
201/// Installs `host_fd` into a **specific** guest FD slot (for `dup2`).
202///
203/// Closes any previous host mapping at `gfd` (except stdio 0–2 identity).
204/// Guest nonblock flag is **not** updated — caller should copy from the source.
205/// Returns `false` if `gfd` is out of range.
206#[must_use]
207#[inline]
208pub fn fd_install(gfd: i32, host_fd: RawFd) -> bool {
209    if host_fd < 0 || gfd < 3 {
210        return false;
211    }
212    let Ok(idx) = usize::try_from(gfd) else {
213        return false;
214    };
215    let Some(slot) = FD_HOST.get(idx) else {
216        return false;
217    };
218    let prev = slot.swap(host_fd, Ordering::AcqRel);
219    if prev >= 0 && prev != host_fd {
220        host::close_fd(prev);
221    }
222    true
223}
224
225/// Allocates a guest FD slot for `host_fd` (lock-free CAS scan).
226///
227/// New slots start with guest-blocking semantics (`O_NONBLOCK` clear). Call
228/// [`fd_set_guest_nonblock`] for sockets / after `fcntl(F_SETFL)`.
229#[must_use]
230#[inline]
231pub fn fd_alloc(host_fd: RawFd) -> Option<i32> {
232    if host_fd < 0 {
233        return None;
234    }
235    let start = usize::try_from(FD_NEXT.load(Ordering::Relaxed).max(3)).unwrap_or(3);
236    for idx in start..FD_SLOTS {
237        if try_claim_slot(idx, host_fd) {
238            let gfd = i32::try_from(idx).ok()?;
239            fd_set_guest_nonblock(gfd, false);
240            FD_NEXT.store(gfd.saturating_add(1), Ordering::Relaxed);
241            return Some(gfd);
242        }
243    }
244    for idx in 3..start.min(FD_SLOTS) {
245        if try_claim_slot(idx, host_fd) {
246            let gfd = i32::try_from(idx).ok()?;
247            fd_set_guest_nonblock(gfd, false);
248            FD_NEXT.store(gfd.saturating_add(1), Ordering::Relaxed);
249            return Some(gfd);
250        }
251    }
252    None
253}
254
255/// Guest-visible `O_NONBLOCK` for `gfd` (stdio or allocated slot).
256#[must_use]
257#[inline]
258pub fn fd_guest_nonblock(gfd: i32) -> bool {
259    if gfd < 0 {
260        return false;
261    }
262    let Ok(idx) = usize::try_from(gfd) else {
263        return false;
264    };
265    FD_GUEST_NB
266        .get(idx)
267        .is_some_and(|s| s.load(Ordering::Acquire) != 0)
268}
269
270/// Sets guest-visible `O_NONBLOCK` for `gfd`.
271#[inline]
272pub fn fd_set_guest_nonblock(gfd: i32, nonblock: bool) {
273    if gfd < 0 {
274        return;
275    }
276    let Ok(idx) = usize::try_from(gfd) else {
277        return;
278    };
279    if let Some(slot) = FD_GUEST_NB.get(idx) {
280        slot.store(u8::from(nonblock), Ordering::Release);
281    }
282}
283
284/// True when `gfd` is a TLS-wrapped guest FD (hot path; no mutex).
285#[must_use]
286#[inline]
287pub fn fd_is_tls(gfd: i32) -> bool {
288    if gfd < 0 {
289        return false;
290    }
291    let Ok(idx) = usize::try_from(gfd) else {
292        return false;
293    };
294    FD_TLS
295        .get(idx)
296        .is_some_and(|s| s.load(Ordering::Acquire) != 0)
297}
298
299/// Mark / clear TLS session association for `gfd` (paired with [`crate::tls_fd`]).
300#[inline]
301pub fn fd_set_tls(gfd: i32, is_tls: bool) {
302    if gfd < 0 {
303        return;
304    }
305    let Ok(idx) = usize::try_from(gfd) else {
306        return;
307    };
308    if let Some(slot) = FD_TLS.get(idx) {
309        slot.store(u8::from(is_tls), Ordering::Release);
310    }
311}
312
313/// Clear host `O_NONBLOCK` on stdio when the fd is a pipe/FIFO.
314///
315/// Nested `kh run` (git helpers after `fork`+re-exec) inherits command pipes as
316/// host 0/1/2. Those pipes are created non-blocking for curl multi; helpers
317/// expect Darwin blocking stdin/stdout. Call once per guest run start.
318pub fn normalize_stdio_pipes_blocking() {
319    for fd in 0_i32..=2 {
320        if host::fd_is_fifo(fd) {
321            host::clear_nonblock(fd);
322            fd_set_guest_nonblock(fd, false);
323        }
324    }
325}
326
327/// Bottle root published for path translation (set once per run; rare updates).
328static BOTTLE_ROOT: RwLock<Option<Arc<PathBuf>>> = RwLock::new(None);
329
330/// Open `O_DIRECTORY` fd for the bottle root (`-1` = none).
331///
332/// Hot path: absolute guest paths use `openat`/`fstatat` against this fd
333/// instead of building `{root}/{rel}` PathBuf + `open` from `/` each call (B1).
334static BOTTLE_DIRFD: AtomicI32 = AtomicI32::new(-1);
335
336/// `bsdthread_register` snapshot (narrow lock; not the full process state).
337static BSDTHREAD_REG: RwLock<Option<BsdThreadReg>> = RwLock::new(None);
338
339fn try_claim_slot(idx: usize, host_fd: RawFd) -> bool {
340    let Some(slot) = FD_HOST.get(idx) else {
341        return false;
342    };
343    slot.compare_exchange(FD_EMPTY, host_fd, Ordering::AcqRel, Ordering::Relaxed)
344        .is_ok()
345}
346
347fn reset_fd_map() {
348    for (i, slot) in FD_HOST.iter().enumerate() {
349        let prev = slot.swap(FD_EMPTY, Ordering::AcqRel);
350        if i > 2 && prev >= 0 {
351            host::close_fd(prev);
352        }
353    }
354    for slot in &FD_GUEST_NB {
355        slot.store(0, Ordering::Relaxed);
356    }
357    for slot in &FD_TLS {
358        slot.store(0, Ordering::Relaxed);
359    }
360    STDIO_CLOSED.store(0, Ordering::Relaxed);
361    FD_NEXT.store(3, Ordering::Relaxed);
362}
363
364/// Owned process state for one guest (or unit-test isolation via reset).
365///
366/// Bottle root and `bsdthread_register` live in separate process-wide slots so
367/// open/create hot paths do not take this lock.
368#[derive(Debug)]
369pub struct ProcessState {
370    fds: FdTable,
371    /// Guest FD → directory stream (for `readdir` host helper).
372    dir_streams: HashMap<i32, host::HostDir>,
373    sig_mask: u32,
374    sigactions: [SoftSigAct; 32],
375}
376
377impl ProcessState {
378    /// Fresh process state with default syscall limit.
379    #[must_use]
380    pub fn new() -> Self {
381        Self {
382            fds: FdTable::new(),
383            dir_streams: HashMap::new(),
384            sig_mask: 0,
385            sigactions: [SoftSigAct::zero(); 32],
386        }
387    }
388
389    /// Resets FD table, soft signals, thread reg, and counters. Preserves bottle root.
390    pub fn reset_run(&mut self, max_syscalls: usize) {
391        self.dir_streams.clear();
392        self.fds.reset();
393        self.sig_mask = 0;
394        self.sigactions = [SoftSigAct::zero(); 32];
395        clear_bsdthread_reg();
396        let max = u64::try_from(max_syscalls).unwrap_or(256);
397        MAX_SYSCALLS.store(max, Ordering::Relaxed);
398        SYSCALL_COUNT.store(0, Ordering::Relaxed);
399        LIVE_CHILDREN.store(0, Ordering::Relaxed);
400        crate::thread::reset_thread_runtime();
401    }
402
403    /// Closes any directory stream associated with `gfd` (call before FD free).
404    pub(crate) fn close_dir_stream(&mut self, gfd: i32) {
405        drop(self.dir_streams.remove(&gfd));
406    }
407
408    /// Returns the next directory entry for `gfd`, opening a stream on first use.
409    ///
410    /// `None` means end-of-directory (or empty). `Err(errno)` on failure.
411    pub(crate) fn readdir_next(&mut self, gfd: i32) -> Result<Option<(Vec<u8>, u8)>, i64> {
412        let Some(host_fd) = fd_get(gfd) else {
413            return Err(9); // EBADF
414        };
415
416        if let std::collections::hash_map::Entry::Vacant(e) = self.dir_streams.entry(gfd) {
417            match host::HostDir::open_dup(host_fd) {
418                Ok(dir) => {
419                    e.insert(dir);
420                }
421                Err(err) => return Err(i64::from(err)),
422            }
423        }
424
425        let Some(stream) = self.dir_streams.get_mut(&gfd) else {
426            return Err(9);
427        };
428        Ok(stream.read_next())
429    }
430
431    #[must_use]
432    pub(crate) fn sig_mask(&self) -> u32 {
433        self.sig_mask
434    }
435
436    pub(crate) fn set_sig_mask(&mut self, mask: u32) {
437        self.sig_mask = mask;
438    }
439
440    #[must_use]
441    pub(crate) fn sigaction(&self, sig: usize) -> Option<SoftSigAct> {
442        self.sigactions.get(sig).copied()
443    }
444
445    pub(crate) fn set_sigaction(&mut self, sig: usize, act: SoftSigAct) -> bool {
446        if let Some(slot) = self.sigactions.get_mut(sig) {
447            *slot = act;
448            true
449        } else {
450            false
451        }
452    }
453}
454
455impl Default for ProcessState {
456    fn default() -> Self {
457        Self::new()
458    }
459}
460
461/// Parent observed a successful `fork` (child pid > 0).
462#[inline]
463pub fn child_born() {
464    LIVE_CHILDREN.fetch_add(1, Ordering::Relaxed);
465}
466
467/// Parent reaped at least one child via `waitpid`/`wait4`.
468#[inline]
469pub fn child_reaped() {
470    let _ = LIVE_CHILDREN.fetch_update(Ordering::Relaxed, Ordering::Relaxed, |n| {
471        Some(n.saturating_sub(1))
472    });
473}
474
475/// Number of unreaped host children (approximate; for pipe blocking heuristics).
476#[must_use]
477#[inline]
478pub fn live_children() -> u64 {
479    LIVE_CHILDREN.load(Ordering::Relaxed)
480}
481
482/// Bumps the process-wide syscall counter without taking the process lock.
483///
484/// Returns `true` when the configured max has been exceeded.
485#[must_use]
486pub fn tick_syscall() -> bool {
487    let n = SYSCALL_COUNT.fetch_add(1, Ordering::Relaxed);
488    n >= MAX_SYSCALLS.load(Ordering::Relaxed)
489}
490
491fn active_lock() -> &'static RwLock<ProcessState> {
492    static ACTIVE: OnceLock<RwLock<ProcessState>> = OnceLock::new();
493    ACTIVE.get_or_init(|| RwLock::new(ProcessState::new()))
494}
495
496/// Exclusive access to the active process state.
497pub fn with_mut<R>(f: impl FnOnce(&mut ProcessState) -> R) -> R {
498    match active_lock().write() {
499        Ok(mut guard) => f(&mut guard),
500        Err(poisoned) => f(&mut poisoned.into_inner()),
501    }
502}
503
504/// Shared access to the active process state (concurrent FD lookups, etc.).
505pub fn with_ref<R>(f: impl FnOnce(&ProcessState) -> R) -> R {
506    match active_lock().read() {
507        Ok(guard) => f(&guard),
508        Err(poisoned) => f(&poisoned.into_inner()),
509    }
510}
511
512/// Resets FD/signals/counters for a new guest run (keeps bottle root).
513pub fn reset_run(max_syscalls: usize) {
514    with_mut(|p| p.reset_run(max_syscalls));
515    // After re-exec of a Mach-O helper, host 0/1/2 may be O_NONBLOCK pipes
516    // created for curl multi in the parent — restore Darwin blocking stdio.
517    normalize_stdio_pipes_blocking();
518}
519
520/// Configures the bottle root used by path-taking syscalls.
521///
522/// Also opens/replaces the process-wide bottle directory fd for B1 `openat`.
523pub fn set_bottle_root(root: Option<PathBuf>) {
524    let new_fd = root
525        .as_ref()
526        .map_or(-1, |p| open_bottle_dirfd(p).unwrap_or(-1));
527    let old_fd = BOTTLE_DIRFD.swap(new_fd, Ordering::AcqRel);
528    if old_fd >= 0 {
529        host::close_fd(old_fd);
530    }
531
532    let next = root.map(Arc::new);
533    match BOTTLE_ROOT.write() {
534        Ok(mut guard) => {
535            *guard = next;
536        }
537        Err(poisoned) => {
538            *poisoned.into_inner() = next;
539        }
540    }
541}
542
543/// Clone of the configured bottle root, if any.
544#[must_use]
545pub fn bottle_root() -> Option<PathBuf> {
546    with_bottle_root(|p| p.map(Path::to_path_buf))
547}
548
549/// Borrow the bottle root without cloning (hot path for path translation).
550///
551/// Uses a **narrow** bottle-root lock (not the full process state).
552pub fn with_bottle_root<R>(f: impl FnOnce(Option<&Path>) -> R) -> R {
553    match BOTTLE_ROOT.read() {
554        Ok(guard) => f(guard.as_ref().map(|a| a.as_path())),
555        Err(poisoned) => f(poisoned.into_inner().as_ref().map(|a| a.as_path())),
556    }
557}
558
559/// Process-wide bottle root directory fd for `openat`/`fstatat` (B1).
560///
561/// `None` when no bottle is configured or the directory could not be opened.
562#[must_use]
563pub fn bottle_dirfd() -> Option<RawFd> {
564    let fd = BOTTLE_DIRFD.load(Ordering::Acquire);
565    if fd >= 0 { Some(fd) } else { None }
566}
567
568/// Open `root` as `O_RDONLY|O_DIRECTORY|O_CLOEXEC` for hot-path `openat`.
569fn open_bottle_dirfd(root: &Path) -> Option<RawFd> {
570    let c = std::ffi::CString::new(root.as_os_str().as_encoded_bytes()).ok()?;
571    host::open_directory(&c)
572}
573
574/// Stores `bsdthread_register` metadata for subsequent `bsdthread_create`.
575pub(crate) fn set_bsdthread_reg(reg: BsdThreadReg) {
576    match BSDTHREAD_REG.write() {
577        Ok(mut guard) => {
578            *guard = Some(reg);
579        }
580        Err(poisoned) => {
581            *poisoned.into_inner() = Some(reg);
582        }
583    }
584}
585
586/// Snapshot of the last `bsdthread_register` (narrow lock, copy-out).
587#[must_use]
588pub(crate) fn bsdthread_reg() -> Option<BsdThreadReg> {
589    match BSDTHREAD_REG.read() {
590        Ok(guard) => *guard,
591        Err(poisoned) => *poisoned.into_inner(),
592    }
593}
594
595fn clear_bsdthread_reg() {
596    match BSDTHREAD_REG.write() {
597        Ok(mut guard) => {
598            *guard = None;
599        }
600        Err(poisoned) => {
601            *poisoned.into_inner() = None;
602        }
603    }
604}
605
606/// Serializes tests that mutate process-wide state (address space + process).
607#[cfg(test)]
608pub(crate) fn test_lock() -> std::sync::MutexGuard<'static, ()> {
609    use std::sync::Mutex;
610    static LOCK: Mutex<()> = Mutex::new(());
611    LOCK.lock()
612        .unwrap_or_else(std::sync::PoisonError::into_inner)
613}