1#![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
18pub const DEFAULT_STACK_SIZE: u64 = 8 * 1024 * 1024;
21
22#[derive(Debug, Clone)]
24pub struct RunOptions {
25 pub root: Option<PathBuf>,
27 pub guest_page_size: GuestPageSize,
29 pub guest_args: Vec<String>,
31 pub max_events: usize,
33 pub max_syscalls: usize,
35 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#[derive(Debug)]
54pub struct RunResult {
55 pub exit_code: Option<i32>,
57 pub events: Vec<TrapEvent>,
59 pub patched_svc: usize,
61 pub entry: u64,
63 pub sp: u64,
65 pub slide: u64,
67 pub initializers_run: usize,
69}
70
71pub 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(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 let home = guest_home_env();
116 let mut env_owned = vec![
120 "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 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 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 warn_if_hypercall_env_opt_out();
161 let hypercall_wired = install_libsystem_hypercall(&mut session);
162 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 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 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 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); 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 std::mem::forget(stack);
215 std::mem::forget(session);
216
217 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 if let Some(va) = heap_dump_va {
227 let _ = unsafe { call_guest(va, sp, 0) };
229 }
230
231 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
237fn 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
266fn guest_home_env() -> String {
272 match std::env::var("HOME") {
273 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
298fn 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
317fn 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 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#[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}