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, call_guest,
8    call_guest_args, finish_with_exit_code, install_main_guest_tls, install_trap_handlers,
9    map_stack, patch_svc_to_brk, registry_install, registry_take, set_bottle_root,
10};
11#[cfg(all(target_arch = "aarch64", target_os = "linux"))]
12use kh_runtime::{VM_PROT_EXECUTE, VM_PROT_READ, VM_PROT_WRITE, mprotect_darwin, mprotect_rw};
13
14use crate::error::LoadError;
15use crate::init;
16use crate::session::LoadSession;
17
18/// Default guest stack size for the micro spike (1 MiB).
19/// Guest stack for micro execution (8 MiB — C++ guests like `7zz` use deep frames).
20pub const DEFAULT_STACK_SIZE: u64 = 8 * 1024 * 1024;
21
22/// Options for a micro run / trace.
23#[derive(Debug, Clone)]
24pub struct RunOptions {
25    /// Bottle root (`KAKEHASHI_ROOT` / `--root`) for path translation.
26    pub root: Option<PathBuf>,
27    /// Guest page size policy.
28    pub guest_page_size: GuestPageSize,
29    /// Guest argv (not including argv0 = executable path — that is prepended).
30    pub guest_args: Vec<String>,
31    /// Maximum trap events to retain.
32    pub max_events: usize,
33    /// Maximum syscalls before forced process exit.
34    pub max_syscalls: usize,
35    /// When true, only map (caller should use [`LoadSession::dry_load`] instead).
36    pub dry_load: bool,
37}
38
39impl Default for RunOptions {
40    fn default() -> Self {
41        Self {
42            root: None,
43            guest_page_size: GuestPageSize::default(),
44            guest_args: Vec::new(),
45            max_events: 256,
46            max_syscalls: 256,
47            dry_load: false,
48        }
49    }
50}
51
52/// Result of a completed micro run (when the host does not process-exit).
53#[derive(Debug)]
54pub struct RunResult {
55    /// Exit code if the guest called `exit` without `_exit` from the handler.
56    pub exit_code: Option<i32>,
57    /// Captured trap events (empty if process already exited).
58    pub events: Vec<TrapEvent>,
59    /// Number of `svc` instructions patched to `brk`.
60    pub patched_svc: usize,
61    /// Entry VA used for the jump.
62    pub entry: u64,
63    /// Stack pointer passed to the guest.
64    pub sp: u64,
65    /// Applied **main** image slide.
66    pub slide: u64,
67    /// Number of `mod_init` functions invoked before main.
68    pub initializers_run: usize,
69}
70
71/// Maps, patches, and transfers control to the guest entry.
72///
73/// On a successful guest `exit`, this function **does not return**: the trap
74/// handler terminates the process with the guest status.
75pub fn run_micro(path: &Path, opts: &RunOptions) -> Result<RunResult, LoadError> {
76    if opts.dry_load {
77        return Err(LoadError::NotImplemented(
78            "run_micro: use LoadSession::dry_load for --dry-load",
79        ));
80    }
81
82    set_bottle_root(opts.root.clone());
83    // Drop any previous active address space (unmaps owned guest mmaps).
84    drop(registry_take());
85
86    let mut session = LoadSession::open_with_guest(path, opts.root.clone(), opts.guest_page_size)?;
87    let _ = session.map_process()?;
88
89    let slide = session
90        .images()
91        .first()
92        .map_or(0, crate::session::ProcessImage::slide);
93    let entry = session
94        .entry_va()
95        .ok_or(LoadError::NotImplemented("image has no entry point"))?;
96
97    let host = session
98        .images()
99        .first()
100        .and_then(|img| img.memory.as_ref())
101        .map(kh_runtime::GuestMemory::host)
102        .ok_or(LoadError::NotImplemented("memory missing"))?;
103
104    let mut stack = map_stack(host, DEFAULT_STACK_SIZE)?;
105
106    let argv0 = path.file_name().and_then(|s| s.to_str()).unwrap_or("guest");
107    let mut argv_owned = Vec::with_capacity(opts.guest_args.len().saturating_add(1));
108    argv_owned.push(argv0.to_owned());
109    argv_owned.extend(opts.guest_args.iter().cloned());
110    let argv_refs: Vec<&str> = argv_owned.iter().map(String::as_str).collect();
111    // Minimal macOS-like environment so guests see a real PATH under the bottle.
112    // HOME bridges the host home via `/Volumes/linux…` so host
113    // `git config --global` (and `~/.gitconfig`) is visible to Apple git under
114    // `kh run`. Fall back to bottle `/var/root` when host HOME is unset/odd.
115    let home = guest_home_env();
116    // Base env + host `GIT_*` (nested re-exec of git-remote-* inherits
117    // `GIT_DIR` / `GIT_OBJECT_DIRECTORY` via inject_kh_env → host environ).
118    // Without this, clone dies: "remote-curl: fetch attempted without a local repo".
119    let mut env_owned = vec![
120        // git-core first so `execvp("git-remote-https")` finds CLT helpers (G4).
121        "PATH=/Library/Developer/CommandLineTools/usr/libexec/git-core:\
122/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
123            .to_owned(),
124        home,
125        "TMPDIR=/tmp".to_owned(),
126    ];
127    for (k, v) in std::env::vars() {
128        if !k.starts_with("GIT_") || k.contains('\0') || v.contains('\0') {
129            continue;
130        }
131        // Soft-cap: skip absurdly large values.
132        if k.len().saturating_add(v.len()) > 512 {
133            continue;
134        }
135        env_owned.push(format!("{k}={v}"));
136    }
137    let env_refs: Vec<&str> = env_owned.iter().map(String::as_str).collect();
138
139    let stack_base = stack.guest_addr;
140    let sp = bootstrap_stack(stack.host_bytes_mut(), stack_base, &argv_refs, &env_refs)
141        .map_err(|err| LoadError::NotImplemented(stack_err_static(&err)))?;
142
143    // Build process address space, then install for trap-path checks / mmap bookkeeping.
144    // Hypercall NEON tramp is mapped separately (once, process-local); residual `svc`→`brk`
145    // needs the registry only for later mmap bookkeeping and SIGTRAP translation.
146    let mut address_space = AddressSpace::new();
147    for img in session.images() {
148        if let Some(memory) = img.memory.as_ref() {
149            for region in memory.regions() {
150                address_space.register_borrowed(region);
151            }
152        }
153    }
154    address_space.register_borrowed(&stack);
155    drop(registry_install(address_space));
156
157    // Wire freestanding libSystem → `kh_hypercall_entry` (sole production BSD path).
158    // Residual Darwin `svc` in fixtures/apps is always rewritten to `brk` below;
159    // that is *not* a second production path (see invariants 7, 12).
160    warn_if_hypercall_env_opt_out();
161    let hypercall_wired = install_libsystem_hypercall(&mut session);
162    // Rewrite any leftover Darwin `svc` so Linux never executes them as host syscalls.
163    let mut patched_svc = 0usize;
164    for memory in session.mapped_memories_mut() {
165        patched_svc = patched_svc
166            .saturating_add(patch_svc_to_brk(memory.regions_mut()).map_err(trap_to_load)?);
167    }
168
169    install_trap_handlers(&TrapConfig {
170        max_events: opts.max_events,
171        max_syscalls: opts.max_syscalls,
172    })
173    .map_err(trap_to_load)?;
174
175    // Main-thread guest TLS (TPIDR_EL0) before constructors / LC_MAIN touch errno.
176    let main_tls = install_main_guest_tls();
177    if main_tls != 0 {
178        tracing::debug!(
179            main_tls = format_args!("{main_tls:#x}"),
180            "installed main guest TLS (TPIDR_EL0)"
181        );
182    }
183
184    // dyld-order: constructors (dylibs bottom-up, then main) before LC_MAIN.
185    let initializers_run = init::run_initializers(&session, sp)?;
186
187    tracing::info!(
188        entry = format_args!("{entry:#x}"),
189        sp = format_args!("{sp:#x}"),
190        slide,
191        patched_svc,
192        hypercall_wired,
193        main_tls = format_args!("{main_tls:#x}"),
194        initializers_run,
195        images = session.images().len(),
196        root = ?opts.root,
197        "jumping to guest entry"
198    );
199
200    // Darwin `main(argc, argv, envp, apple)` register setup from the stack image:
201    //   [sp+0] = argc, [sp+8] = argv[0], …, NULL, envp…, NULL, apple NULL.
202    let argc = u64::try_from(argv_owned.len()).unwrap_or(0);
203    let argv_ptr = sp.wrapping_add(8);
204    let envp_ptr = argv_ptr.wrapping_add(argc.saturating_add(1).saturating_mul(8));
205    let apple_ptr = envp_ptr.wrapping_add(8); // empty env → envp NULL then apple NULL
206
207    // Resolve freestanding heap dump before forget (exports live on session).
208    // `main` return never enters guest `_exit`, so dig counters need this call.
209    let heap_dump_va = freestanding_export_va(&session, "_kh_heap_stats_dump")
210        .or_else(|| freestanding_export_va(&session, "kh_heap_stats_dump"));
211
212    // Keep stack / session alive across the call (may noreturn via guest exit).
213    // `forget` retains all GuestMemory owners if exit traps.
214    std::mem::forget(stack);
215    std::mem::forget(session);
216
217    // SAFETY: image is mapped RX, entry points into __TEXT, stack is bootstrapped,
218    // trap handlers installed for Linux aarch64. Uses `blr` so `return` from
219    // `main` resumes the host (dyld-equivalent); guest `exit` still `_exit`s.
220    let status = unsafe {
221        call_guest_args(entry, sp, argc, argv_ptr, envp_ptr, apple_ptr)
222            .map_err(|err| LoadError::PageLayout(err.to_string()))?
223    };
224
225    // Dump freestanding heap stats (guest stderr) before host process exit.
226    if let Some(va) = heap_dump_va {
227        // SAFETY: VA is freestanding export; stack still mapped; may hypercall write(2).
228        let _ = unsafe { call_guest(va, sp, 0) };
229    }
230
231    // dyld: exit(main(...)). Low 32 bits as signed process status (Darwin int).
232    let low = u32::try_from(status & 0xffff_ffff).unwrap_or(0);
233    let code = i32::from_ne_bytes(low.to_ne_bytes());
234    finish_with_exit_code(code);
235}
236
237/// Guest VA of a freestanding `libSystem` export (nlist + slide), if present.
238fn freestanding_export_va(session: &LoadSession, name: &str) -> Option<u64> {
239    let mut any = None;
240    for img in session.images() {
241        let path = img.path.to_string_lossy();
242        let is_libsystem = path.contains("libSystem") || path.contains("libkh_libsystem");
243        for exp in &img.exports {
244            if exp.name != name {
245                continue;
246            }
247            let va = exp.value.saturating_add(img.slide());
248            if is_libsystem {
249                return Some(va);
250            }
251            if any.is_none() {
252                any = Some(va);
253            }
254        }
255    }
256    any
257}
258
259fn stack_err_static(err: &kh_runtime::StackError) -> &'static str {
260    match err {
261        kh_runtime::StackError::TooSmall { .. } => "guest stack too small",
262        kh_runtime::StackError::InvalidString => "invalid stack string",
263    }
264}
265
266/// Guest `HOME=…` for the bootstrap env block.
267///
268/// Prefer host `$HOME` under the `/Volumes/linux` bridge so tools that honour
269/// global config (Apple `git` → `~/.gitconfig`) see the same files as host CLI
270/// config commands. Falls back to bottle `/var/root`.
271fn guest_home_env() -> String {
272    match std::env::var("HOME") {
273        // Nested `kh run` (re-exec of a Mach-O helper) inherits the *guest*
274        // env as host environ — HOME is already `/Volumes/linux…`. Do not
275        // prefix again or `~/.gitconfig` resolves to a doubled path (G4).
276        Ok(h) if h.starts_with("/Volumes/linux") && !h.contains('\0') => {
277            format!("HOME={h}")
278        }
279        Ok(h) if h.starts_with('/') && !h.contains('\0') => {
280            format!("HOME=/Volumes/linux{h}")
281        }
282        _ => "HOME=/var/root".to_owned(),
283    }
284}
285
286fn trap_to_load(err: TrapError) -> LoadError {
287    match err {
288        TrapError::Map(map_err) => LoadError::Map(map_err),
289        TrapError::UnsupportedArch => LoadError::PageLayout(
290            "trap backend requires Linux aarch64 for live execution".to_owned(),
291        ),
292        TrapError::SignalSetup(io_err) => {
293            LoadError::PageLayout(format!("trap signal setup: {io_err}"))
294        }
295    }
296}
297
298/// `KAKEHASHI_HYPERCALL=0` used to force freestanding `svc`→SIGTRAP for A/B
299/// path digs. That opt-out is **removed**: production always wires hypercall.
300/// Residual `svc`→`brk` still runs for fixtures; it is not a dual product path.
301fn warn_if_hypercall_env_opt_out() {
302    let Some(v) = std::env::var_os("KAKEHASHI_HYPERCALL") else {
303        return;
304    };
305    let off = v == "0"
306        || v.eq_ignore_ascii_case("false")
307        || v.eq_ignore_ascii_case("no")
308        || v.eq_ignore_ascii_case("off");
309    if off {
310        tracing::warn!(
311            "KAKEHASHI_HYPERCALL={v:?} is ignored; freestanding hypercall is always wired \
312             (use residual svc→brk only for unpatched fixtures, not as a product path)"
313        );
314    }
315}
316
317/// Point freestanding `libSystem`'s `_kh_bsd_hypercall` at host dispatch.
318///
319/// Returns whether the slot was found and written. On non-Linux hosts this is a
320/// no-op (`false`).
321fn install_libsystem_hypercall(session: &mut LoadSession) -> bool {
322    #[cfg(not(all(target_arch = "aarch64", target_os = "linux")))]
323    {
324        let _ = session;
325        false
326    }
327    #[cfg(all(target_arch = "aarch64", target_os = "linux"))]
328    {
329        install_libsystem_hypercall_linux(session)
330    }
331}
332
333#[cfg(all(target_arch = "aarch64", target_os = "linux"))]
334fn install_libsystem_hypercall_linux(session: &mut LoadSession) -> bool {
335    // Freestanding thin call → host alt stack + NEON tramp + dispatch.
336    let entry_u64 = kh_runtime::hypercall_entry_addr();
337    if entry_u64 == 0 {
338        return false;
339    }
340
341    let mut wired_entry = false;
342    for img in session.images_mut() {
343        let slide = img.slide();
344        let exports: Vec<_> = img.exports.clone();
345        for exp in exports {
346            let slot = exp.name.as_str();
347            if slot != "_kh_bsd_hypercall" && slot != "kh_bsd_hypercall" {
348                continue;
349            }
350            let va = exp.value.saturating_add(slide);
351            if !write_libsystem_u64(img, va, entry_u64) {
352                continue;
353            }
354            wired_entry = true;
355            tracing::info!(
356                va = format_args!("{va:#x}"),
357                entry = format_args!("{entry_u64:#x}"),
358                "wired libSystem BSD hypercall"
359            );
360        }
361    }
362    wired_entry
363}
364
365/// Write 8 little-endian bytes at guest VA in an image mapping (mprotect if needed).
366#[cfg(all(target_arch = "aarch64", target_os = "linux"))]
367fn write_libsystem_u64(img: &mut crate::session::ProcessImage, va: u64, value: u64) -> bool {
368    let Some(memory) = img.memory.as_mut() else {
369        return false;
370    };
371    let Some(region_idx) = memory.regions().iter().position(|region| {
372        let start = region.guest_addr;
373        let end = start.saturating_add(u64::try_from(region.host_len()).unwrap_or(0));
374        va >= start && va.saturating_add(8) <= end
375    }) else {
376        return false;
377    };
378    let Some(region) = memory.regions().get(region_idx) else {
379        return false;
380    };
381    let old_prot = region.prot;
382    let need_rw = old_prot & VM_PROT_WRITE == 0;
383    if need_rw {
384        let Some(region) = memory.regions_mut().get_mut(region_idx) else {
385            return false;
386        };
387        if mprotect_rw(region).is_err() {
388            return false;
389        }
390    }
391    let ok = memory.write_u64_le(va, value).is_some();
392    if need_rw {
393        let mut restore = (old_prot | VM_PROT_READ) & !VM_PROT_WRITE;
394        if old_prot & VM_PROT_EXECUTE != 0 {
395            restore |= VM_PROT_EXECUTE;
396        }
397        if let Some(region) = memory.regions_mut().get_mut(region_idx) {
398            drop(mprotect_darwin(region, restore));
399            region.prot = restore;
400        }
401    }
402    ok
403}