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/// Allocates a guest FD slot for `host_fd` (lock-free CAS scan).
123#[must_use]
124#[inline]
125pub fn fd_alloc(host_fd: RawFd) -> Option<i32> {
126    if host_fd < 0 {
127        return None;
128    }
129    let start = usize::try_from(FD_NEXT.load(Ordering::Relaxed).max(3)).unwrap_or(3);
130    for idx in start..FD_SLOTS {
131        if try_claim_slot(idx, host_fd) {
132            let gfd = i32::try_from(idx).ok()?;
133            FD_NEXT.store(gfd.saturating_add(1), Ordering::Relaxed);
134            return Some(gfd);
135        }
136    }
137    for idx in 3..start.min(FD_SLOTS) {
138        if try_claim_slot(idx, host_fd) {
139            let gfd = i32::try_from(idx).ok()?;
140            FD_NEXT.store(gfd.saturating_add(1), Ordering::Relaxed);
141            return Some(gfd);
142        }
143    }
144    None
145}
146
147/// Bottle root published for path translation (set once per run; rare updates).
148static BOTTLE_ROOT: RwLock<Option<Arc<PathBuf>>> = RwLock::new(None);
149
150/// `bsdthread_register` snapshot (narrow lock; not the full process state).
151static BSDTHREAD_REG: RwLock<Option<BsdThreadReg>> = RwLock::new(None);
152
153fn try_claim_slot(idx: usize, host_fd: RawFd) -> bool {
154    let Some(slot) = FD_HOST.get(idx) else {
155        return false;
156    };
157    slot.compare_exchange(FD_EMPTY, host_fd, Ordering::AcqRel, Ordering::Relaxed)
158        .is_ok()
159}
160
161fn reset_fd_map() {
162    for (i, slot) in FD_HOST.iter().enumerate() {
163        let prev = slot.swap(FD_EMPTY, Ordering::AcqRel);
164        if i > 2 && prev >= 0 {
165            host::close_fd(prev);
166        }
167    }
168    FD_NEXT.store(3, Ordering::Relaxed);
169}
170
171/// Owned process state for one guest (or unit-test isolation via reset).
172///
173/// Bottle root and `bsdthread_register` live in separate process-wide slots so
174/// open/create hot paths do not take this lock.
175#[derive(Debug)]
176pub struct ProcessState {
177    fds: FdTable,
178    /// Guest FD → directory stream (for `readdir` host helper).
179    dir_streams: HashMap<i32, host::HostDir>,
180    sig_mask: u32,
181    sigactions: [SoftSigAct; 32],
182}
183
184impl ProcessState {
185    /// Fresh process state with default syscall limit.
186    #[must_use]
187    pub fn new() -> Self {
188        Self {
189            fds: FdTable::new(),
190            dir_streams: HashMap::new(),
191            sig_mask: 0,
192            sigactions: [SoftSigAct::zero(); 32],
193        }
194    }
195
196    /// Resets FD table, soft signals, thread reg, and counters. Preserves bottle root.
197    pub fn reset_run(&mut self, max_syscalls: usize) {
198        self.dir_streams.clear();
199        self.fds.reset();
200        self.sig_mask = 0;
201        self.sigactions = [SoftSigAct::zero(); 32];
202        clear_bsdthread_reg();
203        let max = u64::try_from(max_syscalls).unwrap_or(256);
204        MAX_SYSCALLS.store(max, Ordering::Relaxed);
205        SYSCALL_COUNT.store(0, Ordering::Relaxed);
206        crate::thread::reset_thread_runtime();
207    }
208
209    /// Closes any directory stream associated with `gfd` (call before FD free).
210    pub(crate) fn close_dir_stream(&mut self, gfd: i32) {
211        drop(self.dir_streams.remove(&gfd));
212    }
213
214    /// Returns the next directory entry for `gfd`, opening a stream on first use.
215    ///
216    /// `None` means end-of-directory (or empty). `Err(errno)` on failure.
217    pub(crate) fn readdir_next(&mut self, gfd: i32) -> Result<Option<(Vec<u8>, u8)>, i64> {
218        let Some(host_fd) = fd_get(gfd) else {
219            return Err(9); // EBADF
220        };
221
222        if let std::collections::hash_map::Entry::Vacant(e) = self.dir_streams.entry(gfd) {
223            match host::HostDir::open_dup(host_fd) {
224                Ok(dir) => {
225                    e.insert(dir);
226                }
227                Err(err) => return Err(i64::from(err)),
228            }
229        }
230
231        let Some(stream) = self.dir_streams.get_mut(&gfd) else {
232            return Err(9);
233        };
234        Ok(stream.read_next())
235    }
236
237    #[must_use]
238    pub(crate) fn sig_mask(&self) -> u32 {
239        self.sig_mask
240    }
241
242    pub(crate) fn set_sig_mask(&mut self, mask: u32) {
243        self.sig_mask = mask;
244    }
245
246    #[must_use]
247    pub(crate) fn sigaction(&self, sig: usize) -> Option<SoftSigAct> {
248        self.sigactions.get(sig).copied()
249    }
250
251    pub(crate) fn set_sigaction(&mut self, sig: usize, act: SoftSigAct) -> bool {
252        if let Some(slot) = self.sigactions.get_mut(sig) {
253            *slot = act;
254            true
255        } else {
256            false
257        }
258    }
259}
260
261impl Default for ProcessState {
262    fn default() -> Self {
263        Self::new()
264    }
265}
266
267/// Bumps the process-wide syscall counter without taking the process lock.
268///
269/// Returns `true` when the configured max has been exceeded.
270#[must_use]
271pub fn tick_syscall() -> bool {
272    let n = SYSCALL_COUNT.fetch_add(1, Ordering::Relaxed);
273    n >= MAX_SYSCALLS.load(Ordering::Relaxed)
274}
275
276fn active_lock() -> &'static RwLock<ProcessState> {
277    static ACTIVE: OnceLock<RwLock<ProcessState>> = OnceLock::new();
278    ACTIVE.get_or_init(|| RwLock::new(ProcessState::new()))
279}
280
281/// Exclusive access to the active process state.
282pub fn with_mut<R>(f: impl FnOnce(&mut ProcessState) -> R) -> R {
283    match active_lock().write() {
284        Ok(mut guard) => f(&mut guard),
285        Err(poisoned) => f(&mut poisoned.into_inner()),
286    }
287}
288
289/// Shared access to the active process state (concurrent FD lookups, etc.).
290pub fn with_ref<R>(f: impl FnOnce(&ProcessState) -> R) -> R {
291    match active_lock().read() {
292        Ok(guard) => f(&guard),
293        Err(poisoned) => f(&poisoned.into_inner()),
294    }
295}
296
297/// Resets FD/signals/counters for a new guest run (keeps bottle root).
298pub fn reset_run(max_syscalls: usize) {
299    with_mut(|p| p.reset_run(max_syscalls));
300}
301
302/// Configures the bottle root used by path-taking syscalls.
303pub fn set_bottle_root(root: Option<PathBuf>) {
304    let next = root.map(Arc::new);
305    match BOTTLE_ROOT.write() {
306        Ok(mut guard) => {
307            *guard = next;
308        }
309        Err(poisoned) => {
310            *poisoned.into_inner() = next;
311        }
312    }
313}
314
315/// Clone of the configured bottle root, if any.
316#[must_use]
317pub fn bottle_root() -> Option<PathBuf> {
318    with_bottle_root(|p| p.map(Path::to_path_buf))
319}
320
321/// Borrow the bottle root without cloning (hot path for path translation).
322///
323/// Uses a **narrow** bottle-root lock (not the full process state).
324pub fn with_bottle_root<R>(f: impl FnOnce(Option<&Path>) -> R) -> R {
325    match BOTTLE_ROOT.read() {
326        Ok(guard) => f(guard.as_ref().map(|a| a.as_path())),
327        Err(poisoned) => f(poisoned.into_inner().as_ref().map(|a| a.as_path())),
328    }
329}
330
331/// Stores `bsdthread_register` metadata for subsequent `bsdthread_create`.
332pub(crate) fn set_bsdthread_reg(reg: BsdThreadReg) {
333    match BSDTHREAD_REG.write() {
334        Ok(mut guard) => {
335            *guard = Some(reg);
336        }
337        Err(poisoned) => {
338            *poisoned.into_inner() = Some(reg);
339        }
340    }
341}
342
343/// Snapshot of the last `bsdthread_register` (narrow lock, copy-out).
344#[must_use]
345pub(crate) fn bsdthread_reg() -> Option<BsdThreadReg> {
346    match BSDTHREAD_REG.read() {
347        Ok(guard) => *guard,
348        Err(poisoned) => *poisoned.into_inner(),
349    }
350}
351
352fn clear_bsdthread_reg() {
353    match BSDTHREAD_REG.write() {
354        Ok(mut guard) => {
355            *guard = None;
356        }
357        Err(poisoned) => {
358            *poisoned.into_inner() = None;
359        }
360    }
361}
362
363/// Serializes tests that mutate process-wide state (address space + process).
364#[cfg(test)]
365pub(crate) fn test_lock() -> std::sync::MutexGuard<'static, ()> {
366    use std::sync::Mutex;
367    static LOCK: Mutex<()> = Mutex::new(());
368    LOCK.lock()
369        .unwrap_or_else(std::sync::PoisonError::into_inner)
370}