Skip to main content

kh_runtime/syscall/
mod.rs

1//! Table-driven Darwin BSD syscall dispatch (arm64, number in `x16`).
2//!
3//! Error ABI (Darwin arm64): success clears `PSTATE.C` and places the return
4//! value in `x0`; failure sets `PSTATE.C` and places a **positive** errno in
5//! `x0`. The trap handler applies the carry bit from [`SyscallResult::error`].
6//!
7//! Modules:
8//! - [`table`] — numbers / names
9//! - [`fd`] — FD table, open/close/dup/lseek/fcntl/openat
10//! - [`io`] — read/write
11//! - [`fs`] — access/stat/fstat
12//! - [`mem_sys`] — mmap/mprotect/munmap/msync
13//! - [`process`] — exit/getpid/issetugid
14//! - [`thread_sys`] — bsdthread_*/thread_selfid
15//! - [`time_sys`] — gettimeofday/clock_gettime
16//! - [`sysctl`] — sysctl/sysctlbyname
17//! - [`signal`] — sigprocmask/sigaction (soft)
18
19mod common;
20mod fd;
21mod fs;
22mod helpers;
23mod io;
24mod mem_sys;
25mod process;
26mod signal;
27mod sysctl;
28mod table;
29mod thread_sys;
30mod time_sys;
31
32use crate::process as proc_state;
33use crate::trap::TrapOutcome;
34
35pub use common::{
36    EBADF, EEXIST, EFAULT, EINVAL, ENOENT, ENOMEM, ENOSYS, EPERM, SyscallArgs, SyscallResult,
37};
38pub use table::{BsdSyscall, known_syscalls, lookup, name_of};
39
40/// Resets FD table, soft signal state, and syscall counter for a new run.
41pub fn reset_syscall_state(max_syscalls: usize) {
42    proc_state::reset_run(max_syscalls);
43}
44
45/// Dispatches a Darwin BSD syscall by number.
46pub fn dispatch(args: SyscallArgs) -> SyscallResult {
47    // Atomic tick — do not take the process lock on every SVC.
48    if proc_state::tick_syscall() {
49        return SyscallResult {
50            name: "max_syscalls",
51            outcome: TrapOutcome::Exit { code: 1 },
52            retval: Some(1),
53            error: false,
54        };
55    }
56
57    // Hot numbers first (archive I/O + helpers) — avoid enum match churn.
58    match args.number {
59        // helpers: 0x4B48_xxxx
60        n if helpers::is_helper(n) => return helpers::dispatch_helper(args),
61        3 | 396 => return io::handle_read(args),
62        4 | 397 => return io::handle_write(args),
63        5 | 398 => return fd::handle_open(args),
64        6 | 399 => return fd::handle_close(args),
65        199 => return fd::handle_lseek(args),
66        92 => return fd::handle_fcntl(args),
67        _ => {}
68    }
69
70    match lookup(args.number) {
71        Some(BsdSyscall::Exit) => process::handle_exit(args),
72        Some(BsdSyscall::Write) => io::handle_write(args),
73        Some(BsdSyscall::Read) => io::handle_read(args),
74        Some(BsdSyscall::Open) => fd::handle_open(args),
75        Some(BsdSyscall::Close) => fd::handle_close(args),
76        Some(BsdSyscall::Getpid) => process::handle_getpid(),
77        Some(BsdSyscall::Access) => fs::handle_access(args),
78        Some(BsdSyscall::Issetugid) => process::handle_issetugid(),
79        Some(BsdSyscall::Munmap) => mem_sys::handle_munmap(args),
80        Some(BsdSyscall::Mprotect) => mem_sys::handle_mprotect(args),
81        Some(BsdSyscall::Mmap) => mem_sys::handle_mmap(args),
82        Some(BsdSyscall::Msync) => mem_sys::handle_msync(args),
83        Some(BsdSyscall::Dup) => fd::handle_dup(args),
84        Some(BsdSyscall::Fcntl) => fd::handle_fcntl(args),
85        Some(BsdSyscall::Lseek) => fd::handle_lseek(args),
86        Some(BsdSyscall::Stat) => fs::handle_stat(args),
87        Some(BsdSyscall::Fstat) => fs::handle_fstat(args),
88        Some(BsdSyscall::Lstat) => fs::handle_lstat(args),
89        Some(BsdSyscall::Unlink) => fs::handle_unlink(args),
90        Some(BsdSyscall::Mkdir) => fs::handle_mkdir(args),
91        Some(BsdSyscall::Rmdir) => fs::handle_rmdir(args),
92        Some(BsdSyscall::Rename) => fs::handle_rename(args),
93        Some(BsdSyscall::Ftruncate) => fs::handle_ftruncate(args),
94        Some(BsdSyscall::Fsync) => fs::handle_fsync(args),
95        Some(BsdSyscall::Openat) => fd::handle_openat(args),
96        Some(BsdSyscall::Fstatat) => fs::handle_fstatat(args),
97        Some(BsdSyscall::Gettimeofday) => time_sys::handle_gettimeofday(args),
98        Some(BsdSyscall::ClockGettime) => time_sys::handle_clock_gettime(args),
99        Some(BsdSyscall::Sysctl) => sysctl::handle_sysctl(args),
100        Some(BsdSyscall::Sysctlbyname) => sysctl::handle_sysctlbyname(args),
101        Some(BsdSyscall::Sigprocmask) => signal::handle_sigprocmask(args),
102        Some(BsdSyscall::Sigaction) => signal::handle_sigaction(args),
103        Some(BsdSyscall::BsdthreadCreate) => thread_sys::handle_bsdthread_create(args),
104        Some(BsdSyscall::BsdthreadTerminate) => thread_sys::handle_bsdthread_terminate(args),
105        Some(BsdSyscall::BsdthreadRegister) => thread_sys::handle_bsdthread_register(args),
106        Some(BsdSyscall::ThreadSelfid) => thread_sys::handle_thread_selfid(),
107        None => {
108            // Rate-limited diagnostic so hangs (e.g. 7zz archive) show the
109            // missing Darwin number without flooding when guests spin.
110            log_unknown_syscall(args.number, args.x0, args.x1, args.x2);
111            SyscallResult::err("unknown", ENOSYS)
112        }
113    }
114}
115
116fn log_unknown_syscall(number: u32, x0: u64, x1: u64, x2: u64) {
117    use std::sync::atomic::{AtomicU32, Ordering};
118    static SEEN: AtomicU32 = AtomicU32::new(0);
119    let n = SEEN.fetch_add(1, Ordering::Relaxed);
120    if n >= 32 {
121        return;
122    }
123    let msg = format!("kh: unknown BSD syscall #{number} x0={x0:#x} x1={x1:#x} x2={x2:#x}\n");
124    drop(std::io::Write::write_all(&mut std::io::stderr(), msg.as_bytes()));
125}
126
127#[cfg(test)]
128#[allow(clippy::expect_used, clippy::unwrap_used)]
129mod tests {
130    use super::common::{guest_read_i32, guest_read_u64, guest_slice, guest_write};
131    use super::mem_sys::{DARWIN_MAP_ANON, DARWIN_MAP_PRIVATE, DARWIN_MAP_SHARED, host_page_size};
132    use super::*;
133    use crate::mem::{
134        HostPageSize, VM_PROT_EXECUTE, VM_PROT_READ, VM_PROT_WRITE, map_stack, register_borrowed,
135        registry_clear,
136    };
137    use std::io::Write;
138
139    fn lock_syscalls() -> std::sync::MutexGuard<'static, ()> {
140        proc_state::test_lock()
141    }
142
143    fn args(number: u32, x0: u64, x1: u64, x2: u64) -> SyscallArgs {
144        SyscallArgs {
145            pc: 0,
146            number,
147            x0,
148            x1,
149            x2,
150            x3: 0,
151            x4: 0,
152            x5: 0,
153            x6: 0,
154        }
155    }
156
157    fn guest_va(base: u64, off: usize) -> u64 {
158        base.wrapping_add(u64::try_from(off).unwrap())
159    }
160
161    fn write_cstr(base: u64, off: usize, s: &str) -> u64 {
162        let va = guest_va(base, off);
163        guest_write(va, s.as_bytes());
164        guest_write(va.wrapping_add(u64::try_from(s.len()).unwrap()), &[0]);
165        va
166    }
167
168    #[test]
169    fn lookup_common_numbers() {
170        assert_eq!(lookup(1), Some(BsdSyscall::Exit));
171        assert_eq!(lookup(4), Some(BsdSyscall::Write));
172        assert_eq!(lookup(5), Some(BsdSyscall::Open));
173        assert_eq!(lookup(20), Some(BsdSyscall::Getpid));
174        assert_eq!(lookup(41), Some(BsdSyscall::Dup));
175        assert_eq!(lookup(46), Some(BsdSyscall::Sigaction));
176        assert_eq!(lookup(48), Some(BsdSyscall::Sigprocmask));
177        assert_eq!(lookup(65), Some(BsdSyscall::Msync));
178        assert_eq!(lookup(92), Some(BsdSyscall::Fcntl));
179        assert_eq!(lookup(116), Some(BsdSyscall::Gettimeofday));
180        assert_eq!(lookup(199), Some(BsdSyscall::Lseek));
181        assert_eq!(lookup(202), Some(BsdSyscall::Sysctl));
182        assert_eq!(lookup(266), Some(BsdSyscall::ClockGettime));
183        assert_eq!(lookup(274), Some(BsdSyscall::Sysctlbyname));
184        assert_eq!(lookup(360), Some(BsdSyscall::BsdthreadCreate));
185        assert_eq!(lookup(361), Some(BsdSyscall::BsdthreadTerminate));
186        assert_eq!(lookup(366), Some(BsdSyscall::BsdthreadRegister));
187        assert_eq!(lookup(372), Some(BsdSyscall::ThreadSelfid));
188        assert_eq!(lookup(463), Some(BsdSyscall::Openat));
189        assert_eq!(lookup(9999), None);
190    }
191
192    #[test]
193    fn name_table_stable() {
194        assert_eq!(name_of(1), Some("exit"));
195        assert_eq!(name_of(4), Some("write"));
196        assert_eq!(name_of(339), Some("fstat"));
197        assert_eq!(name_of(42), None);
198    }
199
200    #[test]
201    fn exit_dispatch() {
202        let _g = lock_syscalls();
203        reset_syscall_state(256);
204        let r = dispatch(args(1, 7, 0, 0));
205        assert_eq!(r.name, "exit");
206        assert_eq!(r.outcome, TrapOutcome::Exit { code: 7 });
207        assert!(!r.error);
208    }
209
210    #[test]
211    fn unknown_returns_enosys_with_error_flag() {
212        let _g = lock_syscalls();
213        reset_syscall_state(256);
214        let r = dispatch(args(0xDEAD, 0, 0, 0));
215        assert_eq!(r.name, "unknown");
216        assert!(r.error);
217        assert_eq!(r.retval, Some(u64::try_from(ENOSYS).unwrap_or(0)));
218    }
219
220    #[test]
221    fn max_syscalls_trips() {
222        let _g = lock_syscalls();
223        reset_syscall_state(2);
224        let a = args(20, 0, 0, 0);
225        assert_eq!(dispatch(a).name, "getpid");
226        assert_eq!(dispatch(a).name, "getpid");
227        let r = dispatch(a);
228        assert_eq!(r.name, "max_syscalls");
229        assert_eq!(r.outcome, TrapOutcome::Exit { code: 1 });
230    }
231
232    #[test]
233    fn getpid_positive() {
234        let _g = lock_syscalls();
235        reset_syscall_state(256);
236        let r = dispatch(args(20, 0, 0, 0));
237        assert_eq!(r.name, "getpid");
238        assert!(!r.error);
239        assert!(r.retval.unwrap_or(0) > 0);
240    }
241
242    #[test]
243    fn ok_err_helpers() {
244        let ok = SyscallResult::ok("write", 3);
245        assert!(!ok.error);
246        assert_eq!(ok.retval, Some(3));
247        let err = SyscallResult::err("write", EBADF);
248        assert!(err.error);
249        assert_eq!(err.retval, Some(9));
250    }
251
252    #[test]
253    fn mmap_anon_private_roundtrip() {
254        let _g = lock_syscalls();
255        reset_syscall_state(256);
256        registry_clear();
257        let page = host_page_size();
258        let page_u = u64::try_from(page).unwrap_or(4096);
259        let r = dispatch(SyscallArgs {
260            pc: 0,
261            number: 197,
262            x0: 0,
263            x1: page_u,
264            x2: u64::from(VM_PROT_READ | VM_PROT_WRITE),
265            x3: DARWIN_MAP_ANON | DARWIN_MAP_PRIVATE,
266            x4: u64::MAX,
267            x5: 0,
268            x6: 0,
269        });
270        assert_eq!(r.name, "mmap");
271        assert!(!r.error, "mmap failed: {:?}", r.retval);
272        let addr = r.retval.expect("addr");
273        assert_ne!(addr, u64::MAX);
274        assert_ne!(addr, 0);
275
276        let r2 = dispatch(SyscallArgs {
277            pc: 0,
278            number: 74,
279            x0: addr,
280            x1: page_u,
281            x2: u64::from(VM_PROT_READ | VM_PROT_EXECUTE),
282            x3: 0,
283            x4: 0,
284            x5: 0,
285            x6: 0,
286        });
287        assert!(!r2.error);
288
289        let r3 = dispatch(SyscallArgs {
290            pc: 0,
291            number: 73,
292            x0: addr,
293            x1: page_u,
294            x2: 0,
295            x3: 0,
296            x4: 0,
297            x5: 0,
298            x6: 0,
299        });
300        assert!(!r3.error);
301        registry_clear();
302    }
303
304    #[test]
305    fn mmap_file_backed_shared_msync() {
306        let _g = lock_syscalls();
307        reset_syscall_state(256);
308        registry_clear();
309        let host = HostPageSize::detect().expect("host");
310        let stack = map_stack(host, 256 * 1024).expect("stack");
311        register_borrowed(&stack);
312
313        let dir = std::env::temp_dir().join(format!("kh-mmap-file-{}", std::process::id()));
314        drop(std::fs::create_dir_all(&dir));
315        let path = dir.join("payload.bin");
316        std::fs::write(&path, b"KAKEMAP01\n").expect("write payload");
317
318        let base = stack.guest_addr;
319        let path_str = path.to_str().unwrap();
320        let path_va = write_cstr(base, 0x1000, path_str);
321        let open = dispatch(args(5, path_va, 2, 0)); // O_RDWR
322        assert!(!open.error, "open: {:?}", open.retval);
323        let gfd = open.retval.expect("fd");
324
325        let page = host_page_size();
326        let page_u = u64::try_from(page).unwrap();
327        let map = dispatch(SyscallArgs {
328            pc: 0,
329            number: 197,
330            x0: 0,
331            x1: page_u,
332            x2: u64::from(VM_PROT_READ | VM_PROT_WRITE),
333            x3: DARWIN_MAP_SHARED,
334            x4: gfd,
335            x5: 0,
336            x6: 0,
337        });
338        assert!(!map.error, "mmap file: {:?}", map.retval);
339        let addr = map.retval.expect("map");
340        assert_eq!(guest_slice(addr, 9), b"KAKEMAP01");
341        guest_write(addr, b"X");
342
343        let sync = dispatch(SyscallArgs {
344            pc: 0,
345            number: 65,
346            x0: addr,
347            x1: page_u,
348            x2: 0x10, // MS_SYNC
349            x3: 0,
350            x4: 0,
351            x5: 0,
352            x6: 0,
353        });
354        assert!(!sync.error, "msync: {:?}", sync.retval);
355
356        let unmap = dispatch(SyscallArgs {
357            pc: 0,
358            number: 73,
359            x0: addr,
360            x1: page_u,
361            x2: 0,
362            x3: 0,
363            x4: 0,
364            x5: 0,
365            x6: 0,
366        });
367        assert!(!unmap.error);
368        assert!(!dispatch(args(6, gfd, 0, 0)).error);
369
370        let on_disk = std::fs::read(&path).expect("reread");
371        assert_eq!(on_disk.first().copied(), Some(b'X'));
372        assert_eq!(on_disk.get(1..9), Some(b"AKEMAP01".as_slice()));
373
374        registry_clear();
375        drop(stack);
376        drop(std::fs::remove_file(&path));
377        drop(std::fs::remove_dir(&dir));
378    }
379
380    #[test]
381    fn gettimeofday_and_clock_gettime() {
382        let _g = lock_syscalls();
383        reset_syscall_state(256);
384        registry_clear();
385        let host = HostPageSize::detect().expect("host");
386        let stack = map_stack(host, 64 * 1024).expect("stack");
387        register_borrowed(&stack);
388        let base = stack.guest_addr;
389        let tv_va = guest_va(base, 0x400);
390        let ts_va = guest_va(base, 0x500);
391
392        let r = dispatch(args(116, tv_va, 0, 0));
393        assert!(!r.error, "gettimeofday: {:?}", r.retval);
394        let sec = guest_read_u64(tv_va);
395        let sec = i64::from_ne_bytes(sec.to_ne_bytes());
396        assert!(sec > 1_600_000_000, "tv_sec={sec}");
397
398        let r2 = dispatch(args(266, 0, ts_va, 0)); // CLOCK_REALTIME
399        assert!(!r2.error, "clock_gettime: {:?}", r2.retval);
400        let sec2 = guest_read_u64(ts_va);
401        let sec2 = i64::from_ne_bytes(sec2.to_ne_bytes());
402        assert!((sec2 - sec).abs() < 5);
403
404        registry_clear();
405        drop(stack);
406    }
407
408    #[test]
409    fn sysctlbyname_hw_ncpu() {
410        let _g = lock_syscalls();
411        reset_syscall_state(256);
412        registry_clear();
413        let host = HostPageSize::detect().expect("host");
414        let stack = map_stack(host, 64 * 1024).expect("stack");
415        register_borrowed(&stack);
416        let base = stack.guest_addr;
417        let key_va = write_cstr(base, 0x200, "hw.ncpu");
418        let val_va = guest_va(base, 0x300);
419        let len_va = guest_va(base, 0x310);
420        guest_write(len_va, &8_u64.to_le_bytes());
421
422        let r = dispatch(SyscallArgs {
423            pc: 0,
424            number: 274,
425            x0: key_va,
426            x1: val_va,
427            x2: len_va,
428            x3: 0,
429            x4: 0,
430            x5: 0,
431            x6: 0,
432        });
433        assert!(!r.error, "sysctlbyname: {:?}", r.retval);
434        let ncpu = guest_read_i32(val_va);
435        assert!(ncpu >= 1);
436
437        registry_clear();
438        drop(stack);
439    }
440
441    #[test]
442    fn sigprocmask_soft_roundtrip() {
443        let _g = lock_syscalls();
444        reset_syscall_state(256);
445        registry_clear();
446        let host = HostPageSize::detect().expect("host");
447        let stack = map_stack(host, 64 * 1024).expect("stack");
448        register_borrowed(&stack);
449        let base = stack.guest_addr;
450        let set_va = guest_va(base, 0x100);
451        let oset_va = guest_va(base, 0x110);
452        guest_write(set_va, &0x00FF_u32.to_le_bytes());
453        // SIG_SETMASK = 3
454        let r = dispatch(SyscallArgs {
455            pc: 0,
456            number: 48,
457            x0: 3,
458            x1: set_va,
459            x2: oset_va,
460            x3: 0,
461            x4: 0,
462            x5: 0,
463            x6: 0,
464        });
465        assert!(!r.error, "sigprocmask: {:?}", r.retval);
466
467        registry_clear();
468        drop(stack);
469    }
470
471    #[test]
472    fn write_efault_when_registry_active_and_bad_ptr() {
473        let _g = lock_syscalls();
474        reset_syscall_state(256);
475        registry_clear();
476        let host = HostPageSize::detect().expect("host");
477        let stack = map_stack(host, 64 * 1024).expect("stack");
478        register_borrowed(&stack);
479
480        let r = dispatch(args(4, 1, 0x1, 4));
481        assert_eq!(r.name, "write");
482        assert!(r.error);
483        assert_eq!(r.retval, Some(u64::try_from(EFAULT).unwrap_or(0)));
484        registry_clear();
485        drop(stack);
486    }
487
488    #[test]
489    fn open_read_lseek_fstat_dup_roundtrip() {
490        let _g = lock_syscalls();
491        reset_syscall_state(256);
492        registry_clear();
493        let host = HostPageSize::detect().expect("host");
494        let stack = map_stack(host, 256 * 1024).expect("stack");
495        register_borrowed(&stack);
496
497        let dir = std::env::temp_dir().join(format!("kh-fd-test-{}", std::process::id()));
498        drop(std::fs::create_dir_all(&dir));
499        let path = dir.join("data.txt");
500        {
501            let mut f = std::fs::File::create(&path).expect("create");
502            f.write_all(b"hello-DEF").expect("write");
503        }
504
505        let base = stack.guest_addr;
506        let path_str = path.to_str().expect("utf8 path");
507        let path_va = write_cstr(base, 0x1000, path_str);
508        let open = dispatch(args(5, path_va, 0, 0)); // O_RDONLY
509        assert!(!open.error, "open: {:?}", open.retval);
510        let gfd = open.retval.expect("fd");
511
512        let read_va = guest_va(base, 0x2000);
513        let rd = dispatch(args(3, gfd, read_va, 5)); // read 5
514        assert!(!rd.error, "read: {:?}", rd.retval);
515        assert_eq!(rd.retval, Some(5));
516        assert_eq!(guest_slice(read_va, 5), b"hello");
517
518        let seek = dispatch(args(199, gfd, 0, 0)); // lseek SET 0
519        assert!(!seek.error);
520        assert_eq!(seek.retval, Some(0));
521
522        let stat_va = guest_va(base, 0x3000);
523        let st = dispatch(args(339, gfd, stat_va, 0));
524        assert!(!st.error, "fstat: {:?}", st.retval);
525        // Darwin stat64: st_size at offset 96.
526        let size = guest_read_u64(stat_va + 96);
527        let size = i64::from_ne_bytes(size.to_ne_bytes());
528        assert_eq!(size, 9);
529
530        let dup = dispatch(args(41, gfd, 0, 0));
531        assert!(!dup.error);
532        let gfd2 = dup.retval.expect("dup fd");
533        assert_ne!(gfd2, gfd);
534
535        let fl = dispatch(args(92, gfd, 3, 0));
536        assert!(!fl.error);
537
538        assert!(!dispatch(args(6, gfd, 0, 0)).error);
539        assert!(!dispatch(args(6, gfd2, 0, 0)).error);
540
541        registry_clear();
542        drop(stack);
543        drop(std::fs::remove_file(&path));
544        drop(std::fs::remove_dir(&dir));
545    }
546
547    #[test]
548    fn openat_at_fdcwd() {
549        let _g = lock_syscalls();
550        reset_syscall_state(256);
551        registry_clear();
552        let host = HostPageSize::detect().expect("host");
553        let stack = map_stack(host, 64 * 1024).expect("stack");
554        register_borrowed(&stack);
555
556        let dir = std::env::temp_dir().join(format!("kh-openat-{}", std::process::id()));
557        drop(std::fs::create_dir_all(&dir));
558        let path = dir.join("x.txt");
559        std::fs::write(&path, b"z").expect("write");
560
561        let base = stack.guest_addr;
562        let path_str = path.to_str().unwrap();
563        let path_va = write_cstr(base, 0x800, path_str);
564        let r = dispatch(SyscallArgs {
565            pc: 0,
566            number: 463,
567            x0: u64::from_ne_bytes(i64::from(fd::AT_FDCWD).to_ne_bytes()),
568            x1: path_va,
569            x2: 0,
570            x3: 0,
571            x4: 0,
572            x5: 0,
573            x6: 0,
574        });
575        assert!(!r.error, "openat: {:?}", r.retval);
576        let gfd = r.retval.unwrap();
577        assert!(!dispatch(args(6, gfd, 0, 0)).error);
578
579        registry_clear();
580        drop(stack);
581        drop(std::fs::remove_file(&path));
582        drop(std::fs::remove_dir(&dir));
583    }
584}