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}