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}