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