Skip to main content

kh_loader/
execute.rs

1//! Micro execution: map, patch traps, bootstrap stack, jump to entry.
2#![allow(unsafe_code)]
3
4use std::path::{Path, PathBuf};
5
6use kh_runtime::{
7    AddressSpace, GuestPageSize, TrapConfig, TrapError, TrapEvent, bootstrap_stack,
8    call_guest_args, clear_trampoline_cache, finish_with_exit_code, install_main_guest_tls,
9    install_trap_handlers, map_stack, patch_svc_to_brk, registry_install, registry_take,
10    set_bottle_root,
11};
12#[cfg(all(target_arch = "aarch64", target_os = "linux"))]
13use kh_runtime::{VM_PROT_EXECUTE, VM_PROT_READ, VM_PROT_WRITE, mprotect_darwin, mprotect_rw};
14
15use crate::error::LoadError;
16use crate::init;
17use crate::session::LoadSession;
18
19/// Default guest stack size for the micro spike (1 MiB).
20/// Guest stack for micro execution (8 MiB — C++ guests like `7zz` use deep frames).
21pub const DEFAULT_STACK_SIZE: u64 = 8 * 1024 * 1024;
22
23/// Options for a micro run / trace.
24#[derive(Debug, Clone)]
25pub struct RunOptions {
26    /// Bottle root (`KAKEHASHI_ROOT` / `--root`) for path translation.
27    pub root: Option<PathBuf>,
28    /// Guest page size policy.
29    pub guest_page_size: GuestPageSize,
30    /// Guest argv (not including argv0 = executable path — that is prepended).
31    pub guest_args: Vec<String>,
32    /// Maximum trap events to retain.
33    pub max_events: usize,
34    /// Maximum syscalls before forced process exit.
35    pub max_syscalls: usize,
36    /// When true, only map (caller should use [`LoadSession::dry_load`] instead).
37    pub dry_load: bool,
38}
39
40impl Default for RunOptions {
41    fn default() -> Self {
42        Self {
43            root: None,
44            guest_page_size: GuestPageSize::default(),
45            guest_args: Vec::new(),
46            max_events: 256,
47            max_syscalls: 256,
48            dry_load: false,
49        }
50    }
51}
52
53/// Result of a completed micro run (when the host does not process-exit).
54#[derive(Debug)]
55pub struct RunResult {
56    /// Exit code if the guest called `exit` without `_exit` from the handler.
57    pub exit_code: Option<i32>,
58    /// Captured trap events (empty if process already exited).
59    pub events: Vec<TrapEvent>,
60    /// Number of `svc` instructions patched to `brk`.
61    pub patched_svc: usize,
62    /// Entry VA used for the jump.
63    pub entry: u64,
64    /// Stack pointer passed to the guest.
65    pub sp: u64,
66    /// Applied **main** image slide.
67    pub slide: u64,
68    /// Number of `mod_init` functions invoked before main.
69    pub initializers_run: usize,
70}
71
72/// Maps, patches, and transfers control to the guest entry.
73///
74/// On a successful guest `exit`, this function **does not return**: the trap
75/// handler terminates the process with the guest status.
76pub fn run_micro(path: &Path, opts: &RunOptions) -> Result<RunResult, LoadError> {
77    if opts.dry_load {
78        return Err(LoadError::NotImplemented(
79            "run_micro: use LoadSession::dry_load for --dry-load",
80        ));
81    }
82
83    set_bottle_root(opts.root.clone());
84    // Drop any previous active address space (unmaps owned guest mmaps).
85    drop(registry_take());
86    // Owned trampoline pages went with the space — never reuse stale VAs.
87    clear_trampoline_cache();
88
89    let mut session = LoadSession::open_with_guest(path, opts.root.clone(), opts.guest_page_size)?;
90    let _ = session.map_process()?;
91
92    let slide = session
93        .images()
94        .first()
95        .map_or(0, crate::session::ProcessImage::slide);
96    let entry = session
97        .entry_va()
98        .ok_or(LoadError::NotImplemented("image has no entry point"))?;
99
100    let host = session
101        .images()
102        .first()
103        .and_then(|img| img.memory.as_ref())
104        .map(kh_runtime::GuestMemory::host)
105        .ok_or(LoadError::NotImplemented("memory missing"))?;
106
107    let mut stack = map_stack(host, DEFAULT_STACK_SIZE)?;
108
109    let argv0 = path.file_name().and_then(|s| s.to_str()).unwrap_or("guest");
110    let mut argv_owned = Vec::with_capacity(opts.guest_args.len().saturating_add(1));
111    argv_owned.push(argv0.to_owned());
112    argv_owned.extend(opts.guest_args.iter().cloned());
113    let argv_refs: Vec<&str> = argv_owned.iter().map(String::as_str).collect();
114    // Minimal macOS-like environment so guests see a real PATH under the bottle.
115    let env_owned = [
116        "PATH=/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin".to_owned(),
117        "HOME=/var/root".to_owned(),
118        "TMPDIR=/tmp".to_owned(),
119    ];
120    let env_refs: Vec<&str> = env_owned.iter().map(String::as_str).collect();
121
122    let stack_base = stack.guest_addr;
123    let sp = bootstrap_stack(stack.host_bytes_mut(), stack_base, &argv_refs, &env_refs)
124        .map_err(|err| LoadError::NotImplemented(stack_err_static(&err)))?;
125
126    // Build process address space, then install for trap-path checks / mmap bookkeeping.
127    // Must install *before* `patch_svc_to_brk`: the Linux trampoline path maps an RX
128    // page and `register_owned`s it. Installing a fresh AddressSpace drops the previous
129    // one and would munmap that trampoline → SIGSEGV on the first `bl`.
130    let mut address_space = AddressSpace::new();
131    for img in session.images() {
132        if let Some(memory) = img.memory.as_ref() {
133            for region in memory.regions() {
134                address_space.register_borrowed(region);
135            }
136        }
137    }
138    address_space.register_borrowed(&stack);
139    drop(registry_install(address_space));
140
141    // Wire freestanding libSystem → host BSD dispatch (no SIGTRAP).
142    // Default ON; opt out with `KAKEHASHI_HYPERCALL=0|false|off|no`.
143    let hypercall_wired = if hypercall_enabled() {
144        install_libsystem_hypercall(&mut session)
145    } else {
146        false
147    };
148    // Rewrite residual Darwin `svc` (binaries not using freestanding hypercall).
149    // After the active registry is live so optional trampoline pages stick.
150    let mut patched_svc = 0usize;
151    for memory in session.mapped_memories_mut() {
152        patched_svc = patched_svc
153            .saturating_add(patch_svc_to_brk(memory.regions_mut()).map_err(trap_to_load)?);
154    }
155
156    install_trap_handlers(&TrapConfig {
157        max_events: opts.max_events,
158        max_syscalls: opts.max_syscalls,
159    })
160    .map_err(trap_to_load)?;
161
162    // Main-thread guest TLS (TPIDR_EL0) before constructors / LC_MAIN touch errno.
163    let main_tls = install_main_guest_tls();
164    if main_tls != 0 {
165        tracing::debug!(
166            main_tls = format_args!("{main_tls:#x}"),
167            "installed main guest TLS (TPIDR_EL0)"
168        );
169    }
170
171    // dyld-order: constructors (dylibs bottom-up, then main) before LC_MAIN.
172    let initializers_run = init::run_initializers(&session, sp)?;
173
174    tracing::info!(
175        entry = format_args!("{entry:#x}"),
176        sp = format_args!("{sp:#x}"),
177        slide,
178        patched_svc,
179        hypercall_wired,
180        main_tls = format_args!("{main_tls:#x}"),
181        initializers_run,
182        images = session.images().len(),
183        root = ?opts.root,
184        "jumping to guest entry"
185    );
186
187    // Darwin `main(argc, argv, envp, apple)` register setup from the stack image:
188    //   [sp+0] = argc, [sp+8] = argv[0], …, NULL, envp…, NULL, apple NULL.
189    let argc = u64::try_from(argv_owned.len()).unwrap_or(0);
190    let argv_ptr = sp.wrapping_add(8);
191    let envp_ptr = argv_ptr.wrapping_add(argc.saturating_add(1).saturating_mul(8));
192    let apple_ptr = envp_ptr.wrapping_add(8); // empty env → envp NULL then apple NULL
193
194    // Keep stack / session alive across the call (may noreturn via guest exit).
195    // `forget` retains all GuestMemory owners if exit traps.
196    std::mem::forget(stack);
197    std::mem::forget(session);
198
199    // SAFETY: image is mapped RX, entry points into __TEXT, stack is bootstrapped,
200    // trap handlers installed for Linux aarch64. Uses `blr` so `return` from
201    // `main` resumes the host (dyld-equivalent); guest `exit` still `_exit`s.
202    let status = unsafe {
203        call_guest_args(entry, sp, argc, argv_ptr, envp_ptr, apple_ptr)
204            .map_err(|err| LoadError::PageLayout(err.to_string()))?
205    };
206
207    // dyld: exit(main(...)). Low 32 bits as signed process status (Darwin int).
208    let low = u32::try_from(status & 0xffff_ffff).unwrap_or(0);
209    let code = i32::from_ne_bytes(low.to_ne_bytes());
210    finish_with_exit_code(code);
211}
212
213fn stack_err_static(err: &kh_runtime::StackError) -> &'static str {
214    match err {
215        kh_runtime::StackError::TooSmall { .. } => "guest stack too small",
216        kh_runtime::StackError::InvalidString => "invalid stack string",
217    }
218}
219
220fn trap_to_load(err: TrapError) -> LoadError {
221    match err {
222        TrapError::Map(map_err) => LoadError::Map(map_err),
223        TrapError::UnsupportedArch => LoadError::PageLayout(
224            "trap backend requires Linux aarch64 for live execution".to_owned(),
225        ),
226        TrapError::SignalSetup(io_err) => {
227            LoadError::PageLayout(format!("trap signal setup: {io_err}"))
228        }
229    }
230}
231
232/// Freestanding libSystem hypercall is on by default (avoids SIGTRAP).
233///
234/// Disable with `KAKEHASHI_HYPERCALL=0|false|off|no`.
235fn hypercall_enabled() -> bool {
236    match std::env::var_os("KAKEHASHI_HYPERCALL") {
237        None => true,
238        Some(v) => {
239            !(v == "0"
240                || v.eq_ignore_ascii_case("false")
241                || v.eq_ignore_ascii_case("no")
242                || v.eq_ignore_ascii_case("off"))
243        }
244    }
245}
246
247/// Point freestanding `libSystem`'s `_kh_bsd_hypercall` at host dispatch.
248///
249/// Returns whether the slot was found and written. On non-Linux hosts this is a
250/// no-op (`false`).
251fn install_libsystem_hypercall(session: &mut LoadSession) -> bool {
252    #[cfg(not(all(target_arch = "aarch64", target_os = "linux")))]
253    {
254        let _ = session;
255        false
256    }
257    #[cfg(all(target_arch = "aarch64", target_os = "linux"))]
258    {
259        install_libsystem_hypercall_linux(session)
260    }
261}
262
263#[cfg(all(target_arch = "aarch64", target_os = "linux"))]
264fn install_libsystem_hypercall_linux(session: &mut LoadSession) -> bool {
265    // Freestanding thin call → host alt stack + NEON tramp + dispatch.
266    let entry_u64 = kh_runtime::hypercall_entry_addr();
267    if entry_u64 == 0 {
268        return false;
269    }
270
271    let workers = hypercall_workers_enabled();
272    let mut wired_entry = false;
273    let mut wired_workers = false;
274
275    for img in session.images_mut() {
276        let slide = img.slide();
277        let exports: Vec<_> = img.exports.clone();
278        for exp in exports {
279            let slot = exp.name.as_str();
280            let is_entry = slot == "_kh_bsd_hypercall" || slot == "kh_bsd_hypercall";
281            let is_workers = slot == "_kh_hypercall_workers" || slot == "kh_hypercall_workers";
282            if !is_entry && !is_workers {
283                continue;
284            }
285            let va = exp.value.saturating_add(slide);
286            let value = if is_entry {
287                entry_u64
288            } else {
289                u64::from(u32::from(workers))
290            };
291            if !write_libsystem_u64(img, va, value) {
292                continue;
293            }
294            if is_entry {
295                wired_entry = true;
296                tracing::info!(
297                    va = format_args!("{va:#x}"),
298                    entry = format_args!("{entry_u64:#x}"),
299                    "wired libSystem BSD hypercall"
300                );
301            } else {
302                wired_workers = true;
303                tracing::info!(
304                    va = format_args!("{va:#x}"),
305                    workers,
306                    "wired libSystem hypercall-workers flag"
307                );
308            }
309        }
310    }
311    let _ = wired_workers;
312    wired_entry
313}
314
315/// Worker hypercall is **on by default** (unified boundary + TPIDR save/restore).
316///
317/// Opt out with `KAKEHASHI_HYPERCALL_WORKERS=0|false|off|no` (legacy dual-path;
318/// not recommended).
319#[cfg(all(target_arch = "aarch64", target_os = "linux"))]
320fn hypercall_workers_enabled() -> bool {
321    match std::env::var_os("KAKEHASHI_HYPERCALL_WORKERS") {
322        None => true,
323        Some(v) => {
324            !(v == "0"
325                || v.eq_ignore_ascii_case("false")
326                || v.eq_ignore_ascii_case("no")
327                || v.eq_ignore_ascii_case("off"))
328        }
329    }
330}
331
332/// Write 8 little-endian bytes at guest VA in an image mapping (mprotect if needed).
333#[cfg(all(target_arch = "aarch64", target_os = "linux"))]
334fn write_libsystem_u64(img: &mut crate::session::ProcessImage, va: u64, value: u64) -> bool {
335    let Some(memory) = img.memory.as_mut() else {
336        return false;
337    };
338    let Some(region_idx) = memory.regions().iter().position(|region| {
339        let start = region.guest_addr;
340        let end = start.saturating_add(u64::try_from(region.host_len()).unwrap_or(0));
341        va >= start && va.saturating_add(8) <= end
342    }) else {
343        return false;
344    };
345    let Some(region) = memory.regions().get(region_idx) else {
346        return false;
347    };
348    let old_prot = region.prot;
349    let need_rw = old_prot & VM_PROT_WRITE == 0;
350    if need_rw {
351        let Some(region) = memory.regions_mut().get_mut(region_idx) else {
352            return false;
353        };
354        if mprotect_rw(region).is_err() {
355            return false;
356        }
357    }
358    let ok = memory.write_u64_le(va, value).is_some();
359    if need_rw {
360        let mut restore = (old_prot | VM_PROT_READ) & !VM_PROT_WRITE;
361        if old_prot & VM_PROT_EXECUTE != 0 {
362            restore |= VM_PROT_EXECUTE;
363        }
364        if let Some(region) = memory.regions_mut().get_mut(region_idx) {
365            drop(mprotect_darwin(region, restore));
366            region.prot = restore;
367        }
368    }
369    ok
370}