Skip to main content

kh_runtime/
entry.rs

1//! Jump / call into mapped guest code (AArch64 only).
2#![allow(unsafe_code)]
3
4use thiserror::Error;
5
6/// Errors when transferring control to guest code.
7#[derive(Debug, Error, Clone, PartialEq, Eq)]
8pub enum EntryError {
9    /// Host is not AArch64.
10    #[error("guest entry requires aarch64 host")]
11    UnsupportedArch,
12
13    /// Entry address is null / obviously invalid.
14    #[error("invalid guest entry address {0:#x}")]
15    InvalidEntry(u64),
16
17    /// Stack pointer is not 16-byte aligned.
18    #[error("stack pointer {0:#x} is not 16-byte aligned")]
19    MisalignedStack(u64),
20}
21
22/// Transfers control to `entry` with stack pointer `sp`.
23///
24/// Does not return on success: guest code must trap into the trap backend
25/// (e.g. Darwin `svc` rewritten as `brk`) which terminates the process.
26///
27/// # Safety
28///
29/// Caller must guarantee:
30/// - `entry` points at executable mapped guest code;
31/// - `sp` points at a valid mapped stack with bootstrapped argv;
32/// - trap handlers are installed if guest may issue syscalls;
33/// - no Rust objects requiring Drop need to run after the jump (or the trap
34///   path exits the process).
35pub unsafe fn jump_to_guest(entry: u64, sp: u64) -> Result<(), EntryError> {
36    // SAFETY: same invariants; extra arg regs zeroed.
37    unsafe { jump_to_guest_args(entry, sp, 0, 0, 0, 0) }
38}
39
40/// Like [`jump_to_guest`], but places `x0`–`x3` before the branch (pthread start).
41///
42/// Does not return: guest must `exit` the process or `bsdthread_terminate` the
43/// host thread (trap backend redirects to host `pthread_exit`).
44///
45/// # Safety
46///
47/// Same as [`jump_to_guest`], plus argument registers must match the guest
48/// entry convention (Darwin `_pthread_start`: pthread, port, func, arg).
49pub unsafe fn jump_to_guest_args(
50    entry: u64,
51    sp: u64,
52    x0: u64,
53    x1: u64,
54    x2: u64,
55    x3: u64,
56) -> Result<(), EntryError> {
57    if entry == 0 {
58        return Err(EntryError::InvalidEntry(entry));
59    }
60    if !sp.is_multiple_of(16) {
61        return Err(EntryError::MisalignedStack(sp));
62    }
63
64    #[cfg(not(target_arch = "aarch64"))]
65    {
66        let _ = (entry, sp, x0, x1, x2, x3);
67        return Err(EntryError::UnsupportedArch);
68    }
69
70    #[cfg(target_arch = "aarch64")]
71    {
72        // SAFETY: caller invariants documented above. We zero FP/LR so a
73        // guest return would fault rather than walk a bogus Rust frame.
74        unsafe {
75            std::arch::asm!(
76                "mov sp, {sp}",
77                "mov x0, {arg0}",
78                "mov x1, {arg1}",
79                "mov x2, {arg2}",
80                "mov x3, {arg3}",
81                "mov x4, xzr",
82                "mov x5, xzr",
83                "mov x6, xzr",
84                "mov x7, xzr",
85                "mov x29, xzr",
86                "mov x30, xzr",
87                "br {entry}",
88                sp = in(reg) sp,
89                arg0 = in(reg) x0,
90                arg1 = in(reg) x1,
91                arg2 = in(reg) x2,
92                arg3 = in(reg) x3,
93                entry = in(reg) entry,
94                options(noreturn),
95            );
96        }
97    }
98}
99
100/// Calls a guest function at `entry` and returns its `x0` to the host.
101///
102/// Uses a real `blr` so a guest `ret` resumes the host. Guest may take Darwin
103/// syscalls via the trap backend (must be installed first if needed). Guest
104/// `exit` still terminates the process.
105///
106/// `arg0` is placed in guest `x0` (remaining argument registers are zeroed).
107///
108/// # Safety
109///
110/// Caller must guarantee:
111/// - `entry` points at executable mapped guest code that returns with `ret`
112///   (or never returns via `exit` / fatal trap);
113/// - `sp` is a valid 16-byte-aligned guest stack;
114/// - trap handlers are installed if the callee may issue syscalls;
115/// - the guest does not unwind into host frames (standard AAPCS64 `ret` only).
116pub unsafe fn call_guest(entry: u64, sp: u64, arg0: u64) -> Result<u64, EntryError> {
117    // SAFETY: same invariants as [`call_guest_args`]; extra arg regs zeroed.
118    unsafe { call_guest_args(entry, sp, arg0, 0, 0, 0) }
119}
120
121/// Like [`call_guest`], but sets guest `x0`–`x3` (Darwin `main` / AAPCS64).
122///
123/// Used for `LC_MAIN` so `return` from `main` resumes the host with the status
124/// in `x0` (dyld then calls `exit`; we do the same via
125/// [`crate::trap::finish_with_exit_code`]).
126///
127/// # Safety
128///
129/// Same as [`call_guest`].
130pub unsafe fn call_guest_args(
131    entry: u64,
132    sp: u64,
133    x0: u64,
134    x1: u64,
135    x2: u64,
136    x3: u64,
137) -> Result<u64, EntryError> {
138    if entry == 0 {
139        return Err(EntryError::InvalidEntry(entry));
140    }
141    if !sp.is_multiple_of(16) {
142        return Err(EntryError::MisalignedStack(sp));
143    }
144
145    #[cfg(not(target_arch = "aarch64"))]
146    {
147        let _ = (entry, sp, x0, x1, x2, x3);
148        return Err(EntryError::UnsupportedArch);
149    }
150
151    #[cfg(target_arch = "aarch64")]
152    {
153        let mut ret: u64;
154        // Host SP must survive the guest call. `clobber_abi("C")` tells LLVM
155        // that `blr` is a full C call, so live values (including host SP) are
156        // kept only in callee-saved regs — never in x18. That matters because
157        // freestanding hypercalls run host Rust under **Linux** AAPCS64 (x18
158        // is scratch) while Darwin guests treat x18 as reserved; parking host
159        // SP in x18 then produced `SIGBUS BUS_ADRALN` at `si_addr=0x1` after
160        // guest `main` returned under `KAKEHASHI_HYPERCALL`.
161        let mut host_sp: u64 = 0;
162        // SAFETY: caller invariants above. `clobber_abi("C")` clobbers x0–x18 /
163        // x30; host SP and ret live in explicit callee-saved regs. x19 is
164        // reserved by LLVM on aarch64 and cannot be an asm operand.
165        unsafe {
166            std::arch::asm!(
167                "mov x20, sp",
168                "mov sp, {guest_sp}",
169                "mov x0, {arg0}",
170                "mov x1, {arg1}",
171                "mov x2, {arg2}",
172                "mov x3, {arg3}",
173                "mov x4, xzr",
174                "mov x5, xzr",
175                "mov x6, xzr",
176                "mov x7, xzr",
177                "blr {entry}",
178                "mov x21, x0",
179                "mov sp, x20",
180                guest_sp = in(reg) sp,
181                arg0 = in(reg) x0,
182                arg1 = in(reg) x1,
183                arg2 = in(reg) x2,
184                arg3 = in(reg) x3,
185                entry = in(reg) entry,
186                inout("x20") host_sp,
187                lateout("x21") ret,
188                clobber_abi("C"),
189            );
190        }
191        let _ = host_sp;
192        Ok(ret)
193    }
194}