Skip to main content

kh_runtime/syscall/
common.rs

1//! Shared syscall types, errno, and guest-memory helpers.
2//!
3//! Guest VA ↔ host pointer helpers assume the identity map model. Callers must
4//! validate ranges with the active address space before reading or writing.
5
6use crate::trap::TrapOutcome;
7
8/// Darwin `errno` values we surface.
9pub const EPERM: i64 = 1;
10pub const ENOENT: i64 = 2;
11pub const EBADF: i64 = 9;
12pub const EFAULT: i64 = 14;
13pub const EEXIST: i64 = 17;
14pub const EINVAL: i64 = 22;
15/// Darwin `ERANGE` (getcwd buffer too small).
16pub(crate) const ERANGE: i64 = 34;
17pub const ENOSYS: i64 = 78;
18pub const ENOMEM: i64 = 12;
19
20/// Arguments for one BSD syscall (AArch64 Darwin convention).
21#[derive(Debug, Clone, Copy)]
22pub struct SyscallArgs {
23    /// Guest PC of the trap instruction.
24    pub pc: u64,
25    /// Syscall number (`x16`).
26    pub number: u32,
27    /// `x0` … `x6` argument registers (Darwin allows up to 8; we need 7 for
28    /// `bsdthread_register`).
29    pub x0: u64,
30    pub x1: u64,
31    pub x2: u64,
32    pub x3: u64,
33    pub x4: u64,
34    pub x5: u64,
35    pub x6: u64,
36}
37
38/// Result of dispatching one syscall.
39#[derive(Debug, Clone)]
40pub struct SyscallResult {
41    /// Stable short name for traces.
42    pub name: &'static str,
43    /// Whether to exit the process or continue the guest.
44    pub outcome: TrapOutcome,
45    /// Value to write back into `x0`. `None` keeps `x0` (e.g. `exit`).
46    pub retval: Option<u64>,
47    /// When true, trap sets `PSTATE.C` and `retval` is a positive errno.
48    pub error: bool,
49}
50
51impl SyscallResult {
52    /// Successful return: clear carry, `x0 = value`.
53    #[must_use]
54    pub const fn ok(name: &'static str, value: u64) -> Self {
55        Self {
56            name,
57            outcome: TrapOutcome::Continue,
58            retval: Some(value),
59            error: false,
60        }
61    }
62
63    /// Error return: set carry, `x0 = positive errno`.
64    #[must_use]
65    pub const fn err(name: &'static str, errno: i64) -> Self {
66        Self {
67            name,
68            outcome: TrapOutcome::Continue,
69            retval: Some(errno.unsigned_abs()),
70            error: true,
71        }
72    }
73
74    /// Guest process exit (no register write-back required).
75    #[must_use]
76    pub const fn exit(code: i32) -> Self {
77        Self {
78            name: "exit",
79            outcome: TrapOutcome::Exit { code },
80            retval: None,
81            error: false,
82        }
83    }
84
85    /// End the current guest **thread** only (`bsdthread_terminate`).
86    #[must_use]
87    pub const fn thread_exit(name: &'static str) -> Self {
88        Self {
89            name,
90            outcome: TrapOutcome::ThreadExit,
91            retval: None,
92            error: false,
93        }
94    }
95}
96
97/// Low 8 bits as process exit status.
98#[must_use]
99pub(crate) fn exit_status(x0: u64) -> i32 {
100    i32::try_from(x0 & 0xFF).unwrap_or(0)
101}
102
103/// Low 32 bits of a register as signed i32 (two's complement).
104#[must_use]
105pub(crate) fn reg_as_i32(x: u64) -> i32 {
106    let lo = u32::try_from(x & 0xFFFF_FFFF).unwrap_or(0);
107    i32::from_ne_bytes(lo.to_ne_bytes())
108}
109
110/// Full 64-bit register as signed i64.
111#[must_use]
112pub(crate) fn reg_as_i64(x: u64) -> i64 {
113    i64::from_ne_bytes(x.to_ne_bytes())
114}
115
116/// Identity-map guest pointer → host `*const u8`.
117#[must_use]
118pub(crate) fn guest_ptr(addr: u64) -> *const u8 {
119    let u = usize::try_from(addr).unwrap_or(0);
120    std::ptr::with_exposed_provenance(u)
121}
122
123/// Identity-map guest pointer → host `*mut u8`.
124#[must_use]
125pub(crate) fn guest_ptr_mut(addr: u64) -> *mut u8 {
126    let u = usize::try_from(addr).unwrap_or(0);
127    std::ptr::with_exposed_provenance_mut(u)
128}
129
130/// Immutable view of `len` guest bytes (identity map).
131///
132/// # Safety contract
133/// Caller must have validated `[addr, addr+len)` as readable guest memory.
134#[must_use]
135#[allow(unsafe_code)]
136pub(crate) fn guest_slice<'a>(addr: u64, len: usize) -> &'a [u8] {
137    if len == 0 {
138        return &[];
139    }
140    // SAFETY: caller validated the range; identity map ⇒ guest VA is host VA.
141    unsafe { std::slice::from_raw_parts(guest_ptr(addr), len) }
142}
143
144/// Mutable view of `len` guest bytes (identity map).
145///
146/// # Safety contract
147/// Caller must have validated `[addr, addr+len)` as writable guest memory.
148#[must_use]
149#[allow(unsafe_code)]
150pub(crate) fn guest_slice_mut<'a>(addr: u64, len: usize) -> &'a mut [u8] {
151    if len == 0 {
152        return &mut [];
153    }
154    // SAFETY: caller validated the range; identity map ⇒ guest VA is host VA.
155    unsafe { std::slice::from_raw_parts_mut(guest_ptr_mut(addr), len) }
156}
157
158/// Write bytes into guest memory (identity map).
159///
160/// # Safety contract
161/// Caller must have validated `[addr, addr+data.len())` as writable guest memory.
162pub(crate) fn guest_write(addr: u64, data: &[u8]) {
163    guest_slice_mut(addr, data.len()).copy_from_slice(data);
164}
165
166/// Read a little-endian `u32` from guest memory.
167#[must_use]
168pub(crate) fn guest_read_u32(addr: u64) -> u32 {
169    let mut le = [0_u8; 4];
170    le.copy_from_slice(guest_slice(addr, 4));
171    u32::from_le_bytes(le)
172}
173
174/// Write a little-endian `u32` into guest memory.
175pub(crate) fn guest_write_u32(addr: u64, value: u32) {
176    guest_write(addr, &value.to_le_bytes());
177}
178
179/// Read a little-endian `u64` from guest memory.
180#[must_use]
181pub(crate) fn guest_read_u64(addr: u64) -> u64 {
182    let mut le = [0_u8; 8];
183    le.copy_from_slice(guest_slice(addr, 8));
184    u64::from_le_bytes(le)
185}
186
187/// Read a little-endian `i32` from guest memory.
188#[must_use]
189pub(crate) fn guest_read_i32(addr: u64) -> i32 {
190    i32::from_ne_bytes(guest_read_u32(addr).to_ne_bytes())
191}