1#![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
20pub const DEFAULT_STACK_SIZE: u64 = 8 * 1024 * 1024;
23
24#[derive(Debug, Clone)]
26pub struct RunOptions {
27 pub root: Option<PathBuf>,
29 pub guest_page_size: GuestPageSize,
31 pub guest_args: Vec<String>,
33 pub max_events: usize,
35 pub max_syscalls: usize,
37 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#[derive(Debug)]
56pub struct RunResult {
57 pub exit_code: Option<i32>,
59 pub events: Vec<TrapEvent>,
61 pub patched_svc: usize,
63 pub entry: u64,
65 pub sp: u64,
67 pub slide: u64,
69 pub initializers_run: usize,
71}
72
73pub 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 let guest_exec = host_path_to_guest(path).or_else(|| {
90 path.to_str().map(str::to_owned)
92 });
93 proc_state::set_guest_executable_path(guest_exec.clone());
94 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 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 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 let home = guest_home_env();
140 let mut env_owned = vec![
144 "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 "TMPDIR=/var/folders/xx/kakehashi_default_user_temp000/T/".to_owned(),
156 ];
157 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 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 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 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 warn_if_hypercall_env_opt_out();
209 let hypercall_wired =
210 crate::load_timing::time("wire_hypercall", || install_libsystem_hypercall(&mut session));
211 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 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 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 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); 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 let setprogname_va = freestanding_export_va(&session, "_setprogname")
272 .or_else(|| freestanding_export_va(&session, "setprogname"));
273
274 crate::load_timing::time("dyld_table", || register_dyld_images(&session));
277
278 crate::load_timing::dump("pre-entry");
280
281 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 let _ = unsafe { call_guest(va, sp, ptr) };
296 }
297 }
298
299 std::mem::forget(stack);
302 std::mem::forget(session);
303
304 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 if let Some(va) = heap_dump_va {
318 let _ = unsafe { call_guest(va, sp, 0) };
320 }
321
322 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
328fn 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
348fn 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
377fn guest_home_env() -> String {
383 match std::env::var("HOME") {
384 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
397const GUEST_DEFAULT_SDKROOT: &str = "/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk";
399
400const GUEST_DEFAULT_DEVELOPER_DIR: &str = "/Library/Developer/CommandLineTools";
402
403fn 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 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
447fn 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
466fn 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 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#[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}