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