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_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    // Owned trampoline pages went with the space — never reuse stale VAs.
86    clear_trampoline_cache();
87
88    let mut session = LoadSession::open_with_guest(path, opts.root.clone(), opts.guest_page_size)?;
89    let _ = session.map_process()?;
90
91    let slide = session
92        .images()
93        .first()
94        .map_or(0, crate::session::ProcessImage::slide);
95    let entry = session
96        .entry_va()
97        .ok_or(LoadError::NotImplemented("image has no entry point"))?;
98
99    let host = session
100        .images()
101        .first()
102        .and_then(|img| img.memory.as_ref())
103        .map(kh_runtime::GuestMemory::host)
104        .ok_or(LoadError::NotImplemented("memory missing"))?;
105
106    let mut stack = map_stack(host, DEFAULT_STACK_SIZE)?;
107
108    let argv0 = path.file_name().and_then(|s| s.to_str()).unwrap_or("guest");
109    let mut argv_owned = Vec::with_capacity(opts.guest_args.len().saturating_add(1));
110    argv_owned.push(argv0.to_owned());
111    argv_owned.extend(opts.guest_args.iter().cloned());
112    let argv_refs: Vec<&str> = argv_owned.iter().map(String::as_str).collect();
113    // Minimal macOS-like environment so guests see a real PATH under the bottle.
114    let env_owned = [
115        "PATH=/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin".to_owned(),
116        "HOME=/var/root".to_owned(),
117        "TMPDIR=/tmp".to_owned(),
118    ];
119    let env_refs: Vec<&str> = env_owned.iter().map(String::as_str).collect();
120
121    let stack_base = stack.guest_addr;
122    let sp = bootstrap_stack(stack.host_bytes_mut(), stack_base, &argv_refs, &env_refs)
123        .map_err(|err| LoadError::NotImplemented(stack_err_static(&err)))?;
124
125    // Build process address space, then install for trap-path checks / mmap bookkeeping.
126    // Must install *before* `patch_svc_to_brk`: the Linux trampoline path maps an RX
127    // page and `register_owned`s it. Installing a fresh AddressSpace drops the previous
128    // one and would munmap that trampoline → SIGSEGV on the first `bl`.
129    let mut address_space = AddressSpace::new();
130    for img in session.images() {
131        if let Some(memory) = img.memory.as_ref() {
132            for region in memory.regions() {
133                address_space.register_borrowed(region);
134            }
135        }
136    }
137    address_space.register_borrowed(&stack);
138    drop(registry_install(address_space));
139
140    // Wire freestanding libSystem → host BSD dispatch (no SIGTRAP).
141    // Default ON; opt out with `KAKEHASHI_HYPERCALL=0|false|off|no`.
142    let hypercall_wired = if hypercall_enabled() {
143        install_libsystem_hypercall(&mut session)
144    } else {
145        false
146    };
147    // Rewrite residual Darwin `svc` (binaries not using freestanding hypercall).
148    // After the active registry is live so optional trampoline pages stick.
149    let mut patched_svc = 0usize;
150    for memory in session.mapped_memories_mut() {
151        patched_svc = patched_svc
152            .saturating_add(patch_svc_to_brk(memory.regions_mut()).map_err(trap_to_load)?);
153    }
154
155    install_trap_handlers(&TrapConfig {
156        max_events: opts.max_events,
157        max_syscalls: opts.max_syscalls,
158    })
159    .map_err(trap_to_load)?;
160
161    // dyld-order: constructors (dylibs bottom-up, then main) before LC_MAIN.
162    let initializers_run = init::run_initializers(&session, sp)?;
163
164    tracing::info!(
165        entry = format_args!("{entry:#x}"),
166        sp = format_args!("{sp:#x}"),
167        slide,
168        patched_svc,
169        hypercall_wired,
170        initializers_run,
171        images = session.images().len(),
172        root = ?opts.root,
173        "jumping to guest entry"
174    );
175
176    // Darwin `main(argc, argv, envp, apple)` register setup from the stack image:
177    //   [sp+0] = argc, [sp+8] = argv[0], …, NULL, envp…, NULL, apple NULL.
178    let argc = u64::try_from(argv_owned.len()).unwrap_or(0);
179    let argv_ptr = sp.wrapping_add(8);
180    let envp_ptr = argv_ptr.wrapping_add(argc.saturating_add(1).saturating_mul(8));
181    let apple_ptr = envp_ptr.wrapping_add(8); // empty env → envp NULL then apple NULL
182
183    // Keep stack / session alive across the call (may noreturn via guest exit).
184    // `forget` retains all GuestMemory owners if exit traps.
185    std::mem::forget(stack);
186    std::mem::forget(session);
187
188    // SAFETY: image is mapped RX, entry points into __TEXT, stack is bootstrapped,
189    // trap handlers installed for Linux aarch64. Uses `blr` so `return` from
190    // `main` resumes the host (dyld-equivalent); guest `exit` still `_exit`s.
191    let status = unsafe {
192        call_guest_args(entry, sp, argc, argv_ptr, envp_ptr, apple_ptr)
193            .map_err(|err| LoadError::PageLayout(err.to_string()))?
194    };
195
196    // dyld: exit(main(...)). Low 32 bits as signed process status (Darwin int).
197    let low = u32::try_from(status & 0xffff_ffff).unwrap_or(0);
198    let code = i32::from_ne_bytes(low.to_ne_bytes());
199    finish_with_exit_code(code);
200}
201
202fn stack_err_static(err: &kh_runtime::StackError) -> &'static str {
203    match err {
204        kh_runtime::StackError::TooSmall { .. } => "guest stack too small",
205        kh_runtime::StackError::InvalidString => "invalid stack string",
206    }
207}
208
209fn trap_to_load(err: TrapError) -> LoadError {
210    match err {
211        TrapError::Map(map_err) => LoadError::Map(map_err),
212        TrapError::UnsupportedArch => LoadError::PageLayout(
213            "trap backend requires Linux aarch64 for live execution".to_owned(),
214        ),
215        TrapError::SignalSetup(io_err) => {
216            LoadError::PageLayout(format!("trap signal setup: {io_err}"))
217        }
218    }
219}
220
221/// Freestanding libSystem hypercall is on by default (avoids SIGTRAP).
222///
223/// Disable with `KAKEHASHI_HYPERCALL=0|false|off|no`.
224fn hypercall_enabled() -> bool {
225    match std::env::var_os("KAKEHASHI_HYPERCALL") {
226        None => true,
227        Some(v) => {
228            !(v == "0"
229                || v.eq_ignore_ascii_case("false")
230                || v.eq_ignore_ascii_case("no")
231                || v.eq_ignore_ascii_case("off"))
232        }
233    }
234}
235
236/// Point freestanding `libSystem`'s `_kh_bsd_hypercall` at host dispatch.
237///
238/// Returns whether the slot was found and written. On non-Linux hosts this is a
239/// no-op (`false`).
240fn install_libsystem_hypercall(session: &mut LoadSession) -> bool {
241    #[cfg(not(all(target_arch = "aarch64", target_os = "linux")))]
242    {
243        let _ = session;
244        false
245    }
246    #[cfg(all(target_arch = "aarch64", target_os = "linux"))]
247    {
248        install_libsystem_hypercall_linux(session)
249    }
250}
251
252#[cfg(all(target_arch = "aarch64", target_os = "linux"))]
253fn install_libsystem_hypercall_linux(session: &mut LoadSession) -> bool {
254    // Freestanding thin call → host alt stack + NEON tramp + dispatch.
255    let entry_u64 = kh_runtime::hypercall_entry_addr();
256    if entry_u64 == 0 {
257        return false;
258    }
259
260    let workers = hypercall_workers_enabled();
261    let mut wired_entry = false;
262    let mut wired_workers = false;
263
264    for img in session.images_mut() {
265        let slide = img.slide();
266        let exports: Vec<_> = img.exports.iter().cloned().collect();
267        for exp in exports {
268            let slot = exp.name.as_str();
269            let is_entry = slot == "_kh_bsd_hypercall" || slot == "kh_bsd_hypercall";
270            let is_workers = slot == "_kh_hypercall_workers" || slot == "kh_hypercall_workers";
271            if !is_entry && !is_workers {
272                continue;
273            }
274            let va = exp.value.saturating_add(slide);
275            let value = if is_entry {
276                entry_u64
277            } else {
278                u64::from(u32::from(workers))
279            };
280            if !write_libsystem_u64(img, va, value) {
281                continue;
282            }
283            if is_entry {
284                wired_entry = true;
285                tracing::info!(
286                    va = format_args!("{va:#x}"),
287                    entry = format_args!("{entry_u64:#x}"),
288                    "wired libSystem BSD hypercall"
289                );
290            } else {
291                wired_workers = true;
292                tracing::info!(
293                    va = format_args!("{va:#x}"),
294                    workers,
295                    "wired libSystem hypercall-workers flag"
296                );
297            }
298        }
299    }
300    let _ = wired_workers;
301    wired_entry
302}
303
304/// `KAKEHASHI_HYPERCALL_WORKERS=1|true|yes|on` → freestanding workers use hypercall.
305#[cfg(all(target_arch = "aarch64", target_os = "linux"))]
306fn hypercall_workers_enabled() -> bool {
307    match std::env::var_os("KAKEHASHI_HYPERCALL_WORKERS") {
308        None => false,
309        Some(v) => {
310            v == "1"
311                || v.eq_ignore_ascii_case("true")
312                || v.eq_ignore_ascii_case("yes")
313                || v.eq_ignore_ascii_case("on")
314        }
315    }
316}
317
318/// Write 8 little-endian bytes at guest VA in an image mapping (mprotect if needed).
319#[cfg(all(target_arch = "aarch64", target_os = "linux"))]
320fn write_libsystem_u64(img: &mut crate::session::ProcessImage, va: u64, value: u64) -> bool {
321    let Some(memory) = img.memory.as_mut() else {
322        return false;
323    };
324    let Some(region_idx) = memory.regions().iter().position(|region| {
325        let start = region.guest_addr;
326        let end = start.saturating_add(u64::try_from(region.host_len()).unwrap_or(0));
327        va >= start && va.saturating_add(8) <= end
328    }) else {
329        return false;
330    };
331    let Some(region) = memory.regions().get(region_idx) else {
332        return false;
333    };
334    let old_prot = region.prot;
335    let need_rw = old_prot & VM_PROT_WRITE == 0;
336    if need_rw {
337        let Some(region) = memory.regions_mut().get_mut(region_idx) else {
338            return false;
339        };
340        if mprotect_rw(region).is_err() {
341            return false;
342        }
343    }
344    let ok = memory.write_u64_le(va, value).is_some();
345    if need_rw {
346        let mut restore = (old_prot | VM_PROT_READ) & !VM_PROT_WRITE;
347        if old_prot & VM_PROT_EXECUTE != 0 {
348            restore |= VM_PROT_EXECUTE;
349        }
350        if let Some(region) = memory.regions_mut().get_mut(region_idx) {
351            drop(mprotect_darwin(region, restore));
352            region.prot = restore;
353        }
354    }
355    ok
356}