Skip to main content

kh_runtime/cpu/
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        // Guest TPIDR only for guest code (see `install_main_guest_tls`).
73        let guest = crate::tls::guest_tpidr();
74        if guest != 0 {
75            crate::tls::enter_guest_tls(guest);
76        }
77        // SAFETY: caller invariants documented above. We zero FP/LR so a
78        // guest return would fault rather than walk a bogus Rust frame.
79        unsafe {
80            std::arch::asm!(
81                "mov sp, {sp}",
82                "mov x0, {arg0}",
83                "mov x1, {arg1}",
84                "mov x2, {arg2}",
85                "mov x3, {arg3}",
86                "mov x4, xzr",
87                "mov x5, xzr",
88                "mov x6, xzr",
89                "mov x7, xzr",
90                "mov x29, xzr",
91                "mov x30, xzr",
92                "br {entry}",
93                sp = in(reg) sp,
94                arg0 = in(reg) x0,
95                arg1 = in(reg) x1,
96                arg2 = in(reg) x2,
97                arg3 = in(reg) x3,
98                entry = in(reg) entry,
99                options(noreturn),
100            );
101        }
102    }
103}
104
105/// Calls a guest function at `entry` and returns its `x0` to the host.
106///
107/// Uses a real `blr` so a guest `ret` resumes the host. Guest may take Darwin
108/// syscalls via the trap backend (must be installed first if needed). Guest
109/// `exit` still terminates the process.
110///
111/// `arg0` is placed in guest `x0` (remaining argument registers are zeroed).
112///
113/// # Safety
114///
115/// Caller must guarantee:
116/// - `entry` points at executable mapped guest code that returns with `ret`
117///   (or never returns via `exit` / fatal trap);
118/// - `sp` is a valid 16-byte-aligned guest stack;
119/// - trap handlers are installed if the callee may issue syscalls;
120/// - the guest does not unwind into host frames (standard AAPCS64 `ret` only).
121pub unsafe fn call_guest(entry: u64, sp: u64, arg0: u64) -> Result<u64, EntryError> {
122    // SAFETY: same invariants as [`call_guest_args`]; extra arg regs zeroed.
123    unsafe { call_guest_args(entry, sp, arg0, 0, 0, 0) }
124}
125
126/// Like [`call_guest`], but sets guest `x0`–`x3` (Darwin `main` / AAPCS64).
127///
128/// Used for `LC_MAIN` so `return` from `main` resumes the host with the status
129/// in `x0` (dyld then calls `exit`; we do the same via
130/// [`crate::trap::finish_with_exit_code`]).
131///
132/// # Safety
133///
134/// Same as [`call_guest`].
135pub unsafe fn call_guest_args(
136    entry: u64,
137    sp: u64,
138    x0: u64,
139    x1: u64,
140    x2: u64,
141    x3: u64,
142) -> Result<u64, EntryError> {
143    if entry == 0 {
144        return Err(EntryError::InvalidEntry(entry));
145    }
146    if !sp.is_multiple_of(16) {
147        return Err(EntryError::MisalignedStack(sp));
148    }
149
150    #[cfg(not(target_arch = "aarch64"))]
151    {
152        let _ = (entry, sp, x0, x1, x2, x3);
153        return Err(EntryError::UnsupportedArch);
154    }
155
156    #[cfg(target_arch = "aarch64")]
157    {
158        let mut ret: u64;
159        // Host SP must survive the guest call. `clobber_abi("C")` tells LLVM
160        // that `blr` is a full C call, so live values (including host SP) are
161        // kept only in callee-saved regs — never in x18. That matters because
162        // freestanding hypercalls run host Rust under **Linux** AAPCS64 (x18
163        // is scratch) while Darwin guests treat x18 as reserved; parking host
164        // SP in x18 then produced `SIGBUS BUS_ADRALN` at `si_addr=0x1` after
165        // guest `main` returned under freestanding hypercall.
166        let mut host_sp: u64 = 0;
167        // Guest TPIDR only around guest code; restore host before returning to
168        // Rust (constructors / `main` return path use host TLS for logging etc.).
169        let guest = crate::tls::guest_tpidr();
170        if guest != 0 {
171            crate::tls::enter_guest_tls(guest);
172        }
173        // SAFETY: caller invariants above. `clobber_abi("C")` clobbers x0–x18 /
174        // x30; host SP and ret live in explicit callee-saved regs. x19 is
175        // reserved by LLVM on aarch64 and cannot be an asm operand.
176        unsafe {
177            std::arch::asm!(
178                "mov x20, sp",
179                "mov sp, {guest_sp}",
180                "mov x0, {arg0}",
181                "mov x1, {arg1}",
182                "mov x2, {arg2}",
183                "mov x3, {arg3}",
184                "mov x4, xzr",
185                "mov x5, xzr",
186                "mov x6, xzr",
187                "mov x7, xzr",
188                "blr {entry}",
189                "mov x21, x0",
190                "mov sp, x20",
191                guest_sp = in(reg) sp,
192                arg0 = in(reg) x0,
193                arg1 = in(reg) x1,
194                arg2 = in(reg) x2,
195                arg3 = in(reg) x3,
196                entry = in(reg) entry,
197                inout("x20") host_sp,
198                lateout("x21") ret,
199                clobber_abi("C"),
200            );
201        }
202        crate::tls::enter_host_tls();
203        let _ = host_sp;
204        Ok(ret)
205    }
206}