kh-runtime 0.1.10

Kakehashi native ARM64 execution context, memory layout, traps, and bottle
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
//! Process-wide translator state for the single guest-process model.
//!
//! Hot paths avoid the process [`RwLock`]:
//! - FD map: lock-free atomics ([`fd_get`] / [`fd_alloc`] / [`fd_take`])
//! - bottle root: narrow [`Arc`] slot ([`with_bottle_root`])
//! - `bsdthread_register`: atomic pointer snapshot ([`bsdthread_reg`])
//!
//! Soft signals and directory streams still use [`with_mut`] / [`with_ref`].

use std::collections::HashMap;
use std::os::fd::RawFd;
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicI32, AtomicU64, Ordering};
use std::sync::{Arc, 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);

/// Unreaped host children from guest `fork` (parent side only).
///
/// Used so `read` can emulate Darwin **blocking** notify-pipe waits after
/// spawn while pipes themselves stay `O_NONBLOCK` for curl/c-ares.
static LIVE_CHILDREN: AtomicU64 = AtomicU64::new(0);

/// 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`].
/// Alloc/take update these atomics; dir streams still use the process lock.
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,
        }
    }
}

/// Marker so `ProcessState::reset_run` can clear the lock-free FD map.
#[derive(Debug, Default)]
struct FdTable;

impl FdTable {
    const fn new() -> Self {
        Self
    }

    fn reset(&mut self) {
        let _ = self;
        reset_fd_map();
    }
}

/// 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) }
}

/// 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) }
}

/// Installs `host_fd` into a **specific** guest FD slot (for `dup2`).
///
/// Closes any previous host mapping at `gfd` (except stdio 0–2 identity).
/// Returns `false` if `gfd` is out of range.
#[must_use]
#[inline]
pub fn fd_install(gfd: i32, host_fd: RawFd) -> bool {
    if host_fd < 0 || gfd < 3 {
        return false;
    }
    let Ok(idx) = usize::try_from(gfd) else {
        return false;
    };
    let Some(slot) = FD_HOST.get(idx) else {
        return false;
    };
    let prev = slot.swap(host_fd, Ordering::AcqRel);
    if prev >= 0 && prev != host_fd {
        host::close_fd(prev);
    }
    true
}

/// Allocates a guest FD slot for `host_fd` (lock-free CAS scan).
#[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
}

/// Bottle root published for path translation (set once per run; rare updates).
static BOTTLE_ROOT: RwLock<Option<Arc<PathBuf>>> = RwLock::new(None);

/// Open `O_DIRECTORY` fd for the bottle root (`-1` = none).
///
/// Hot path: absolute guest paths use `openat`/`fstatat` against this fd
/// instead of building `{root}/{rel}` PathBuf + `open` from `/` each call (B1).
static BOTTLE_DIRFD: AtomicI32 = AtomicI32::new(-1);

/// `bsdthread_register` snapshot (narrow lock; not the full process state).
static BSDTHREAD_REG: RwLock<Option<BsdThreadReg>> = RwLock::new(None);

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);
}

/// Owned process state for one guest (or unit-test isolation via reset).
///
/// Bottle root and `bsdthread_register` live in separate process-wide slots so
/// open/create hot paths do not take this lock.
#[derive(Debug)]
pub struct ProcessState {
    fds: FdTable,
    /// Guest FD → directory stream (for `readdir` host helper).
    dir_streams: HashMap<i32, host::HostDir>,
    sig_mask: u32,
    sigactions: [SoftSigAct; 32],
}

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

    /// Resets FD table, soft signals, thread reg, and counters. Preserves bottle root.
    pub fn reset_run(&mut self, max_syscalls: usize) {
        self.dir_streams.clear();
        self.fds.reset();
        self.sig_mask = 0;
        self.sigactions = [SoftSigAct::zero(); 32];
        clear_bsdthread_reg();
        let max = u64::try_from(max_syscalls).unwrap_or(256);
        MAX_SYSCALLS.store(max, Ordering::Relaxed);
        SYSCALL_COUNT.store(0, Ordering::Relaxed);
        LIVE_CHILDREN.store(0, Ordering::Relaxed);
        crate::thread::reset_thread_runtime();
    }

    /// Closes any directory stream associated with `gfd` (call before FD free).
    pub(crate) fn close_dir_stream(&mut self, gfd: i32) {
        drop(self.dir_streams.remove(&gfd));
    }

    /// Returns the next directory entry for `gfd`, opening a stream on first use.
    ///
    /// `None` means end-of-directory (or empty). `Err(errno)` on failure.
    pub(crate) fn readdir_next(&mut self, gfd: i32) -> Result<Option<(Vec<u8>, u8)>, i64> {
        let Some(host_fd) = fd_get(gfd) else {
            return Err(9); // EBADF
        };

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

        let Some(stream) = self.dir_streams.get_mut(&gfd) else {
            return Err(9);
        };
        Ok(stream.read_next())
    }

    #[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()
    }
}

/// Parent observed a successful `fork` (child pid > 0).
#[inline]
pub fn child_born() {
    LIVE_CHILDREN.fetch_add(1, Ordering::Relaxed);
}

/// Parent reaped at least one child via `waitpid`/`wait4`.
#[inline]
pub fn child_reaped() {
    let _ = LIVE_CHILDREN.fetch_update(Ordering::Relaxed, Ordering::Relaxed, |n| {
        Some(n.saturating_sub(1))
    });
}

/// Number of unreaped host children (approximate; for pipe blocking heuristics).
#[must_use]
#[inline]
pub fn live_children() -> u64 {
    LIVE_CHILDREN.load(Ordering::Relaxed)
}

/// 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 (concurrent FD lookups, etc.).
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.
///
/// Also opens/replaces the process-wide bottle directory fd for B1 `openat`.
pub fn set_bottle_root(root: Option<PathBuf>) {
    let new_fd = root.as_ref().map_or(-1, |p| open_bottle_dirfd(p).unwrap_or(-1));
    let old_fd = BOTTLE_DIRFD.swap(new_fd, Ordering::AcqRel);
    if old_fd >= 0 {
        host::close_fd(old_fd);
    }

    let next = root.map(Arc::new);
    match BOTTLE_ROOT.write() {
        Ok(mut guard) => {
            *guard = next;
        }
        Err(poisoned) => {
            *poisoned.into_inner() = next;
        }
    }
}

/// Clone of the configured bottle root, if any.
#[must_use]
pub fn bottle_root() -> Option<PathBuf> {
    with_bottle_root(|p| p.map(Path::to_path_buf))
}

/// Borrow the bottle root without cloning (hot path for path translation).
///
/// Uses a **narrow** bottle-root lock (not the full process state).
pub fn with_bottle_root<R>(f: impl FnOnce(Option<&Path>) -> R) -> R {
    match BOTTLE_ROOT.read() {
        Ok(guard) => f(guard.as_ref().map(|a| a.as_path())),
        Err(poisoned) => f(poisoned.into_inner().as_ref().map(|a| a.as_path())),
    }
}

/// Process-wide bottle root directory fd for `openat`/`fstatat` (B1).
///
/// `None` when no bottle is configured or the directory could not be opened.
#[must_use]
pub fn bottle_dirfd() -> Option<RawFd> {
    let fd = BOTTLE_DIRFD.load(Ordering::Acquire);
    if fd >= 0 { Some(fd) } else { None }
}

/// Open `root` as `O_RDONLY|O_DIRECTORY|O_CLOEXEC` for hot-path `openat`.
fn open_bottle_dirfd(root: &Path) -> Option<RawFd> {
    let c = std::ffi::CString::new(root.as_os_str().as_encoded_bytes()).ok()?;
    host::open_directory(&c)
}

/// Stores `bsdthread_register` metadata for subsequent `bsdthread_create`.
pub(crate) fn set_bsdthread_reg(reg: BsdThreadReg) {
    match BSDTHREAD_REG.write() {
        Ok(mut guard) => {
            *guard = Some(reg);
        }
        Err(poisoned) => {
            *poisoned.into_inner() = Some(reg);
        }
    }
}

/// Snapshot of the last `bsdthread_register` (narrow lock, copy-out).
#[must_use]
pub(crate) fn bsdthread_reg() -> Option<BsdThreadReg> {
    match BSDTHREAD_REG.read() {
        Ok(guard) => *guard,
        Err(poisoned) => *poisoned.into_inner(),
    }
}

fn clear_bsdthread_reg() {
    match BSDTHREAD_REG.write() {
        Ok(mut guard) => {
            *guard = None;
        }
        Err(poisoned) => {
            *poisoned.into_inner() = None;
        }
    }
}

/// 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;
    static LOCK: Mutex<()> = Mutex::new(());
    LOCK.lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner)
}