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::bottle::host_path_to_guest;
7use kh_runtime::process as proc_state;
8use kh_runtime::{
9    AddressSpace, GuestPageSize, TrapConfig, TrapError, TrapEvent, bootstrap_stack, call_guest,
10    call_guest_args, finish_with_exit_code, install_main_guest_tls, install_trap_handlers,
11    map_stack, patch_svc_to_brk, registry_install, registry_take, set_bottle_root,
12};
13#[cfg(all(target_arch = "aarch64", target_os = "linux"))]
14use kh_runtime::{VM_PROT_EXECUTE, VM_PROT_READ, VM_PROT_WRITE, mprotect_darwin, mprotect_rw};
15
16use crate::error::LoadError;
17use crate::init;
18use crate::session::LoadSession;
19
20/// Default guest stack size for the micro spike (1 MiB).
21/// Guest stack for micro execution (8 MiB — C++ guests like `7zz` use deep frames).
22pub const DEFAULT_STACK_SIZE: u64 = 8 * 1024 * 1024;
23
24/// Options for a micro run / trace.
25#[derive(Debug, Clone)]
26pub struct RunOptions {
27    /// Bottle root (`KAKEHASHI_ROOT` / `--root`) for path translation.
28    pub root: Option<PathBuf>,
29    /// Guest page size policy.
30    pub guest_page_size: GuestPageSize,
31    /// Guest argv (not including argv0 = executable path — that is prepended).
32    pub guest_args: Vec<String>,
33    /// Maximum trap events to retain.
34    pub max_events: usize,
35    /// Maximum syscalls before forced process exit.
36    pub max_syscalls: usize,
37    /// When true, only map (caller should use [`LoadSession::dry_load`] instead).
38    pub dry_load: bool,
39}
40
41impl Default for RunOptions {
42    fn default() -> Self {
43        Self {
44            root: None,
45            guest_page_size: GuestPageSize::default(),
46            guest_args: Vec::new(),
47            max_events: 256,
48            max_syscalls: 256,
49            dry_load: false,
50        }
51    }
52}
53
54/// Result of a completed micro run (when the host does not process-exit).
55#[derive(Debug)]
56pub struct RunResult {
57    /// Exit code if the guest called `exit` without `_exit` from the handler.
58    pub exit_code: Option<i32>,
59    /// Captured trap events (empty if process already exited).
60    pub events: Vec<TrapEvent>,
61    /// Number of `svc` instructions patched to `brk`.
62    pub patched_svc: usize,
63    /// Entry VA used for the jump.
64    pub entry: u64,
65    /// Stack pointer passed to the guest.
66    pub sp: u64,
67    /// Applied **main** image slide.
68    pub slide: u64,
69    /// Number of `mod_init` functions invoked before main.
70    pub initializers_run: usize,
71}
72
73/// Maps, patches, and transfers control to the guest entry.
74///
75/// On a successful guest `exit`, this function **does not return**: the trap
76/// handler terminates the process with the guest status.
77pub fn run_micro(path: &Path, opts: &RunOptions) -> Result<RunResult, LoadError> {
78    if opts.dry_load {
79        return Err(LoadError::NotImplemented(
80            "run_micro: use LoadSession::dry_load for --dry-load",
81        ));
82    }
83
84    crate::load_timing::begin_run();
85    crate::load_timing::note(format!("executable={}", path.display()));
86
87    set_bottle_root(opts.root.clone());
88    // Guest-visible main path for `_NSGetExecutablePath` (clang -cc1 re-spawn).
89    let guest_exec = host_path_to_guest(path).or_else(|| {
90        // Bare host path outside bottle: still prefer an absolute guest-ish form.
91        path.to_str().map(str::to_owned)
92    });
93    proc_state::set_guest_executable_path(guest_exec.clone());
94    // Drop any previous active address space (unmaps owned guest mmaps).
95    drop(registry_take());
96
97    let mut session = crate::load_timing::time_result("open_session", || {
98        LoadSession::open_with_guest(path, opts.root.clone(), opts.guest_page_size)
99    })?;
100    // Sub-phases recorded inside `map_process` (map_main / walk_deps / rebase / bind).
101    let _ = session.map_process()?;
102
103    let slide = session
104        .images()
105        .first()
106        .map_or(0, crate::session::ProcessImage::slide);
107    let entry = session
108        .entry_va()
109        .ok_or(LoadError::NotImplemented("image has no entry point"))?;
110
111    let host = session
112        .images()
113        .first()
114        .and_then(|img| img.memory.as_ref())
115        .map(kh_runtime::GuestMemory::host)
116        .ok_or(LoadError::NotImplemented("memory missing"))?;
117
118    let mut stack =
119        crate::load_timing::time_result("map_stack", || map_stack(host, DEFAULT_STACK_SIZE))?;
120
121    // Prefer full guest absolute path as argv0 (Darwin-style); basename fallback.
122    let argv0 = guest_exec.as_deref().filter(|s| !s.is_empty()).map_or_else(
123        || {
124            path.file_name()
125                .and_then(|s| s.to_str())
126                .unwrap_or("guest")
127                .to_owned()
128        },
129        str::to_owned,
130    );
131    let mut argv_owned = Vec::with_capacity(opts.guest_args.len().saturating_add(1));
132    argv_owned.push(argv0);
133    argv_owned.extend(opts.guest_args.iter().cloned());
134    let argv_refs: Vec<&str> = argv_owned.iter().map(String::as_str).collect();
135    // Minimal macOS-like environment so guests see a real PATH under the bottle.
136    // HOME bridges the host home via `/Volumes/linux…` so host
137    // `git config --global` (and `~/.gitconfig`) is visible to Apple git under
138    // `kh run`. Fall back to bottle `/var/root` when host HOME is unset/odd.
139    let home = guest_home_env();
140    // Base env + host `GIT_*` (nested re-exec of git-remote-* inherits
141    // `GIT_DIR` / `GIT_OBJECT_DIRECTORY` via inject_kh_env → host environ).
142    // Without this, clone dies: "remote-curl: fetch attempted without a local repo".
143    let mut env_owned = vec![
144        // git-core first so `execvp("git-remote-https")` finds CLT helpers (G4).
145        // CLT usr/bin next: guest make/cc look up gcc/clang via PATH (bottle
146        // has no /usr/bin gcc shim — only git is symlinked there).
147        "PATH=/Library/Developer/CommandLineTools/usr/libexec/git-core:\
148/Library/Developer/CommandLineTools/usr/bin:\
149/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
150            .to_owned(),
151        home,
152        // Match Darwin `confstr(_CS_DARWIN_USER_TEMP_DIR)` length class
153        // (`/var/folders/…/T/`, ~49 chars). Soft `/tmp` made clang `-flto`
154        // `-object_path_lto` paths too short for freestanding LTO materialize.
155        "TMPDIR=/var/folders/xx/kakehashi_default_user_temp000/T/".to_owned(),
156    ];
157    // Apple clang without a working `xcrun` does not auto-pick
158    // `…/SDKs/MacOSX.sdk` (see `clang -v`: only CLT usr/include). Point the
159    // driver at the bottle SDK when `kh install xcode-tools` laid it down.
160    if let Some(sdk_env) = guest_sdk_env(opts.root.as_deref()) {
161        env_owned.extend(sdk_env);
162    }
163    for (k, v) in std::env::vars() {
164        // Nested re-exec: pass through GIT_* and DYLD_* so guest `main` envp and
165        // freestanding soft-seed (via host getenv) see the same values. Modern
166        // `ld` stages `libLTO` under `/tmp/ld-support-*` and re-execs with
167        // `DYLD_LIBRARY_PATH` set; dropping that var caused an infinite re-exec.
168        let keep = k.starts_with("GIT_")
169            || k == "DYLD_LIBRARY_PATH"
170            || k == "DYLD_FALLBACK_LIBRARY_PATH"
171            || k == "DYLD_FRAMEWORK_PATH";
172        if !keep || k.contains('\0') || v.contains('\0') {
173            continue;
174        }
175        // Soft-cap: skip absurdly large values.
176        if k.len().saturating_add(v.len()) > 512 {
177            continue;
178        }
179        env_owned.push(format!("{k}={v}"));
180    }
181    let env_refs: Vec<&str> = env_owned.iter().map(String::as_str).collect();
182
183    let stack_base = stack.guest_addr;
184    let sp = crate::load_timing::time_result("bootstrap_stack", || {
185        bootstrap_stack(stack.host_bytes_mut(), stack_base, &argv_refs, &env_refs)
186            .map_err(|err| LoadError::NotImplemented(stack_err_static(&err)))
187    })?;
188
189    // Build process address space, then install for trap-path checks / mmap bookkeeping.
190    // Hypercall NEON tramp is mapped separately (once, process-local); residual `svc`→`brk`
191    // needs the registry only for later mmap bookkeeping and SIGTRAP translation.
192    crate::load_timing::time("registry_install", || {
193        let mut address_space = AddressSpace::new();
194        for img in session.images() {
195            if let Some(memory) = img.memory.as_ref() {
196                for region in memory.regions() {
197                    address_space.register_borrowed(region);
198                }
199            }
200        }
201        address_space.register_borrowed(&stack);
202        drop(registry_install(address_space));
203    });
204
205    // Wire freestanding libSystem → `kh_hypercall_entry` (sole production BSD path).
206    // Residual Darwin `svc` is always rewritten to `brk` below;
207    // that is *not* a second production path (see invariants 7, 12).
208    warn_if_hypercall_env_opt_out();
209    let hypercall_wired =
210        crate::load_timing::time("wire_hypercall", || install_libsystem_hypercall(&mut session));
211    // Rewrite any leftover Darwin `svc` so Linux never executes them as host syscalls.
212    let mut patched_svc = 0usize;
213    crate::load_timing::time_result("patch_svc", || {
214        for memory in session.mapped_memories_mut() {
215            patched_svc = patched_svc
216                .saturating_add(patch_svc_to_brk(memory.regions_mut()).map_err(trap_to_load)?);
217        }
218        Ok::<(), LoadError>(())
219    })?;
220
221    crate::load_timing::time_result("install_traps", || {
222        install_trap_handlers(&TrapConfig {
223            max_events: opts.max_events,
224            max_syscalls: opts.max_syscalls,
225        })
226        .map_err(trap_to_load)
227    })?;
228
229    // Main-thread guest TLS (TPIDR_EL0) before constructors / LC_MAIN touch errno.
230    let main_tls = crate::load_timing::time("main_tls", install_main_guest_tls);
231    if main_tls != 0 {
232        tracing::debug!(
233            main_tls = format_args!("{main_tls:#x}"),
234            "installed main guest TLS (TPIDR_EL0)"
235        );
236    }
237
238    // dyld-order: constructors (dylibs bottom-up, then main) before LC_MAIN.
239    let initializers_run =
240        crate::load_timing::time_result("initializers", || init::run_initializers(&session, sp))?;
241
242    tracing::info!(
243        entry = format_args!("{entry:#x}"),
244        sp = format_args!("{sp:#x}"),
245        slide,
246        patched_svc,
247        hypercall_wired,
248        main_tls = format_args!("{main_tls:#x}"),
249        initializers_run,
250        images = session.images().len(),
251        root = ?opts.root,
252        "jumping to guest entry"
253    );
254
255    // Darwin `main(argc, argv, envp, apple)` register setup from the stack image:
256    //   [sp+0] = argc, [sp+8] = argv[0], …, NULL, envp…, NULL, apple NULL.
257    let argc = u64::try_from(argv_owned.len()).unwrap_or(0);
258    let argv_ptr = sp.wrapping_add(8);
259    let envp_ptr = argv_ptr.wrapping_add(argc.saturating_add(1).saturating_mul(8));
260    let apple_ptr = envp_ptr.wrapping_add(8); // empty env → envp NULL then apple NULL
261
262    // Resolve freestanding heap dump before forget (exports live on session).
263    // `main` return never enters guest `_exit`, so dig counters need this call.
264    let heap_dump_va = freestanding_export_va(&session, "_kh_heap_stats_dump")
265        .or_else(|| freestanding_export_va(&session, "kh_heap_stats_dump"));
266
267    // Darwin crt0: `setprogname(argv[0])` before main so `___progname` /
268    // `getprogname()` match the invoked basename. CLT multi-call tools
269    // (`ranlib` → `libtool`) branch on progname; freestanding default
270    // `"kh-guest"` made `ar`'s internal `ranlib -q` fail with "unknown option -q".
271    let setprogname_va = freestanding_export_va(&session, "_setprogname")
272        .or_else(|| freestanding_export_va(&session, "setprogname"));
273
274    // Publish mapped images for freestanding `dlopen`/`dlsym` (e.g. clang's
275    // `-lto_library` re-open of already-loaded `@rpath/libLTO.dylib`).
276    crate::load_timing::time("dyld_table", || register_dyld_images(&session));
277
278    // Dump load phases before guest entry (guest may noreturn via `_exit`).
279    crate::load_timing::dump("pre-entry");
280
281    // Call setprogname while stack is still a live MappedRegion (read argv[0]).
282    if let Some(va) = setprogname_va {
283        let argv0_cstr = {
284            let rel = sp.wrapping_sub(stack_base).wrapping_add(8);
285            let off = usize::try_from(rel).unwrap_or(usize::MAX);
286            stack
287                .host_bytes()
288                .get(off..off.saturating_add(8))
289                .and_then(|b| <[u8; 8]>::try_from(b).ok())
290                .map(u64::from_le_bytes)
291                .filter(|&p| p != 0)
292        };
293        if let Some(ptr) = argv0_cstr {
294            // SAFETY: freestanding `_setprogname`; `ptr` is a stack C string.
295            let _ = unsafe { call_guest(va, sp, ptr) };
296        }
297    }
298
299    // Keep stack / session alive across the call (may noreturn via guest exit).
300    // `forget` retains all GuestMemory owners if exit traps.
301    std::mem::forget(stack);
302    std::mem::forget(session);
303
304    // SAFETY: image is mapped RX, entry points into __TEXT, stack is bootstrapped,
305    // trap handlers installed for Linux aarch64. Uses `blr` so `return` from
306    // `main` resumes the host (dyld-equivalent); guest `exit` still `_exit`s.
307    let guest_t0 = std::time::Instant::now();
308    let status = unsafe {
309        call_guest_args(entry, sp, argc, argv_ptr, envp_ptr, apple_ptr)
310            .map_err(|err| LoadError::PageLayout(err.to_string()))?
311    };
312    let guest_ns = u64::try_from(guest_t0.elapsed().as_nanos()).unwrap_or(u64::MAX);
313    crate::load_timing::record("guest_main_return", guest_ns);
314    crate::load_timing::dump("post-return");
315
316    // Dump freestanding heap stats (guest stderr) before host process exit.
317    if let Some(va) = heap_dump_va {
318        // SAFETY: VA is freestanding export; stack still mapped; may hypercall write(2).
319        let _ = unsafe { call_guest(va, sp, 0) };
320    }
321
322    // dyld: exit(main(...)). Low 32 bits as signed process status (Darwin int).
323    let low = u32::try_from(status & 0xffff_ffff).unwrap_or(0);
324    let code = i32::from_ne_bytes(low.to_ne_bytes());
325    finish_with_exit_code(code);
326}
327
328/// Fill `kh_runtime::dyld_table` from every mapped image (path + slid exports).
329fn register_dyld_images(session: &LoadSession) {
330    use crate::session::ImageLoadStatus;
331    for img in session.images() {
332        if !matches!(img.status, ImageLoadStatus::Mapped) {
333            continue;
334        }
335        let slide = img.slide();
336        let exports = img
337            .exports
338            .iter()
339            .map(|e| (e.name.clone(), e.value.wrapping_add(slide)));
340        kh_runtime::dyld_register_image(
341            img.path.clone(),
342            img.install_name.clone(),
343            exports,
344        );
345    }
346}
347
348/// Guest VA of a freestanding `libSystem` export (nlist + slide), if present.
349fn freestanding_export_va(session: &LoadSession, name: &str) -> Option<u64> {
350    let mut any = None;
351    for img in session.images() {
352        let path = img.path.to_string_lossy();
353        let is_libsystem = path.contains("libSystem") || path.contains("libkh_libsystem");
354        for exp in &img.exports {
355            if exp.name != name {
356                continue;
357            }
358            let va = exp.value.saturating_add(img.slide());
359            if is_libsystem {
360                return Some(va);
361            }
362            if any.is_none() {
363                any = Some(va);
364            }
365        }
366    }
367    any
368}
369
370fn stack_err_static(err: &kh_runtime::StackError) -> &'static str {
371    match err {
372        kh_runtime::StackError::TooSmall { .. } => "guest stack too small",
373        kh_runtime::StackError::InvalidString => "invalid stack string",
374    }
375}
376
377/// Guest `HOME=…` for the bootstrap env block.
378///
379/// Prefer host `$HOME` under the `/Volumes/linux` bridge so tools that honour
380/// global config (Apple `git` → `~/.gitconfig`) see the same files as host CLI
381/// config commands. Falls back to bottle `/var/root`.
382fn guest_home_env() -> String {
383    match std::env::var("HOME") {
384        // Nested `kh run` (re-exec of a Mach-O helper) inherits the *guest*
385        // env as host environ — HOME is already `/Volumes/linux…`. Do not
386        // prefix again or `~/.gitconfig` resolves to a doubled path (G4).
387        Ok(h) if h.starts_with("/Volumes/linux") && !h.contains('\0') => {
388            format!("HOME={h}")
389        }
390        Ok(h) if h.starts_with('/') && !h.contains('\0') => {
391            format!("HOME=/Volumes/linux{h}")
392        }
393        _ => "HOME=/var/root".to_owned(),
394    }
395}
396
397/// Guest absolute default SDK path (CLT layout after `kh install xcode-tools`).
398const GUEST_DEFAULT_SDKROOT: &str = "/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk";
399
400/// Guest absolute CLT developer dir.
401const GUEST_DEFAULT_DEVELOPER_DIR: &str = "/Library/Developer/CommandLineTools";
402
403/// `SDKROOT` + `DEVELOPER_DIR` when the bottle has MacOSX.sdk headers.
404///
405/// Apple clang's default search without a working `xcrun` omits the sysroot;
406/// setting these matches what `xcode-select` + `xcrun --show-sdk-path` provide
407/// on a real Mac with Command Line Tools only.
408fn guest_sdk_env(bottle: Option<&Path>) -> Option<Vec<String>> {
409    let bottle = bottle?;
410    let stdio = bottle
411        .join("Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/stdio.h");
412    if !stdio.is_file() {
413        // Fall back: any MacOSX*.sdk with headers (symlink missing).
414        let sdks = bottle.join("Library/Developer/CommandLineTools/SDKs");
415        let Ok(entries) = std::fs::read_dir(&sdks) else {
416            return None;
417        };
418        let found = entries.flatten().any(|ent| {
419            let name = ent.file_name();
420            let name = name.to_string_lossy();
421            name.starts_with("MacOSX")
422                && name.contains(".sdk")
423                && ent.path().join("usr/include/stdio.h").is_file()
424        });
425        if !found {
426            return None;
427        }
428    }
429    Some(vec![
430        format!("SDKROOT={GUEST_DEFAULT_SDKROOT}"),
431        format!("DEVELOPER_DIR={GUEST_DEFAULT_DEVELOPER_DIR}"),
432    ])
433}
434
435fn trap_to_load(err: TrapError) -> LoadError {
436    match err {
437        TrapError::Map(map_err) => LoadError::Map(map_err),
438        TrapError::UnsupportedArch => LoadError::PageLayout(
439            "trap backend requires Linux aarch64 for live execution".to_owned(),
440        ),
441        TrapError::SignalSetup(io_err) => {
442            LoadError::PageLayout(format!("trap signal setup: {io_err}"))
443        }
444    }
445}
446
447/// `KAKEHASHI_HYPERCALL=0` used to force freestanding `svc`→SIGTRAP for A/B
448/// path digs. That opt-out is **removed**: production always wires hypercall.
449/// Residual `svc`→`brk` still runs for fixtures; it is not a dual product path.
450fn warn_if_hypercall_env_opt_out() {
451    let Some(v) = std::env::var_os("KAKEHASHI_HYPERCALL") else {
452        return;
453    };
454    let off = v == "0"
455        || v.eq_ignore_ascii_case("false")
456        || v.eq_ignore_ascii_case("no")
457        || v.eq_ignore_ascii_case("off");
458    if off {
459        tracing::warn!(
460            "KAKEHASHI_HYPERCALL={v:?} is ignored; freestanding hypercall is always wired \
461             (use residual svc→brk only for unpatched fixtures, not as a product path)"
462        );
463    }
464}
465
466/// Point freestanding `libSystem`'s `_kh_bsd_hypercall` at host dispatch.
467///
468/// Returns whether the slot was found and written. On non-Linux hosts this is a
469/// no-op (`false`).
470fn install_libsystem_hypercall(session: &mut LoadSession) -> bool {
471    #[cfg(not(all(target_arch = "aarch64", target_os = "linux")))]
472    {
473        let _ = session;
474        false
475    }
476    #[cfg(all(target_arch = "aarch64", target_os = "linux"))]
477    {
478        install_libsystem_hypercall_linux(session)
479    }
480}
481
482#[cfg(all(target_arch = "aarch64", target_os = "linux"))]
483fn install_libsystem_hypercall_linux(session: &mut LoadSession) -> bool {
484    // Freestanding thin call → host alt stack + NEON tramp + dispatch.
485    let entry_u64 = kh_runtime::hypercall_entry_addr();
486    if entry_u64 == 0 {
487        return false;
488    }
489
490    let mut wired_entry = false;
491    for img in session.images_mut() {
492        let slide = img.slide();
493        let exports: Vec<_> = img.exports.clone();
494        for exp in exports {
495            let slot = exp.name.as_str();
496            if slot != "_kh_bsd_hypercall" && slot != "kh_bsd_hypercall" {
497                continue;
498            }
499            let va = exp.value.saturating_add(slide);
500            if !write_libsystem_u64(img, va, entry_u64) {
501                continue;
502            }
503            wired_entry = true;
504            tracing::info!(
505                va = format_args!("{va:#x}"),
506                entry = format_args!("{entry_u64:#x}"),
507                "wired libSystem BSD hypercall"
508            );
509        }
510    }
511    wired_entry
512}
513
514/// Write 8 little-endian bytes at guest VA in an image mapping (mprotect if needed).
515#[cfg(all(target_arch = "aarch64", target_os = "linux"))]
516fn write_libsystem_u64(img: &mut crate::session::ProcessImage, va: u64, value: u64) -> bool {
517    let Some(memory) = img.memory.as_mut() else {
518        return false;
519    };
520    let Some(region_idx) = memory.regions().iter().position(|region| {
521        let start = region.guest_addr;
522        let end = start.saturating_add(u64::try_from(region.host_len()).unwrap_or(0));
523        va >= start && va.saturating_add(8) <= end
524    }) else {
525        return false;
526    };
527    let Some(region) = memory.regions().get(region_idx) else {
528        return false;
529    };
530    let old_prot = region.prot;
531    let need_rw = old_prot & VM_PROT_WRITE == 0;
532    if need_rw {
533        let Some(region) = memory.regions_mut().get_mut(region_idx) else {
534            return false;
535        };
536        if mprotect_rw(region).is_err() {
537            return false;
538        }
539    }
540    let ok = memory.write_u64_le(va, value).is_some();
541    if need_rw {
542        let mut restore = (old_prot | VM_PROT_READ) & !VM_PROT_WRITE;
543        if old_prot & VM_PROT_EXECUTE != 0 {
544            restore |= VM_PROT_EXECUTE;
545        }
546        if let Some(region) = memory.regions_mut().get_mut(region_idx) {
547            drop(mprotect_darwin(region, restore));
548            region.prot = restore;
549        }
550    }
551    ok
552}