Skip to main content

kh_runtime/
lib.rs

1//! Native ARM64 execution context, guest memory layout, and trap hooks.
2//!
3//! Dependency rule: this crate must not depend on `kh-loader` or `kh-cli`.
4//!
5//! Layout:
6//! - [`bottle`] — guest root FS / tools install
7//! - [`mem`] — page geometry, mapping, address-space registry
8//! - [`syscall`] — BSD / helper dispatch
9//! - [`cpu`] — registers, trap backend, entry, host-thread slots
10//! - [`thread`] — guest threads + TLS
11//! - [`process`] — process-wide run state, stack, dyld table
12//! - [`host`] — host OS primitives + fat Mach-O open
13//!
14//! `unsafe` is denied by workspace lints and only allowed in tightly scoped
15//! modules (`cpu/*`, `host/*`, `mem/*`, `thread/*`, `syscall` handlers, and
16//! `bottle::read_c_string`).
17
18pub mod bottle;
19pub mod cpu;
20pub mod host;
21pub mod mem;
22pub mod process;
23pub mod syscall;
24pub mod thread;
25
26// Stable paths for modules that used to sit at the crate root.
27pub use cpu::entry;
28pub use cpu::host_slot;
29pub use cpu::regs;
30pub use cpu::trap;
31pub use host::fat_thin;
32pub use process::dyld_table;
33pub use process::stack;
34pub use thread::tls;
35pub use thread::tls_fd;
36pub use thread::tls_verify;
37
38pub use bottle::{
39    BottleError, BottleStatus, CreateOptions, CreateResult, DARWIN_7ZZ_URL, DARWIN_CURL_URL,
40    DEFAULT_7ZZ_PATH, ENV_7ZZ, ENV_CURL, GUEST_7ZZ_REL, GUEST_CURL_REL, GUEST_LIBCURL_REL,
41    GUEST_LIBCURL_TARGET, GUEST_LIBCXX_REL, GUEST_LIBCXX_TARGET, GUEST_PATH_DIRS, InstallPackage,
42    InstallReport, PathError, ToolError, active_root, bottle_root, create as create_bottle,
43    create_with as create_bottle_with, destroy as destroy_bottle, discover_7zz, discover_curl,
44    ensure as ensure_bottle, ensure_libcurl_symlink, ensure_libcxx_symlink, guest_path_to_host,
45    has_libcurl_symlink, has_libcxx_symlink, install_package, package_host_path,
46    resolve_guest_program, set_bottle_root, status as bottle_status, translate_path,
47    translate_path_with_root,
48};
49pub use dyld_table::{
50    RTLD_DEFAULT, RTLD_NEXT, RTLD_SELF, clear as dyld_table_clear, dlopen_lookup, dlsym_lookup,
51    register_image as dyld_register_image,
52};
53pub use process::{ProcessState, reset_run};
54
55pub use entry::{EntryError, call_guest, call_guest_args, jump_to_guest, jump_to_guest_args};
56pub use host::MappedFile;
57pub use mem::{
58    AddressSpace, DARWIN_ARM64_PAGE_SIZE, GuestMemory, GuestPageSize, HostPageSize, MapError,
59    MapRequest, MappedRegion, PageError, PageLayout, VM_PROT_EXECUTE, VM_PROT_READ, VM_PROT_WRITE,
60    map_stack, mprotect_darwin, mprotect_rw, register_borrowed, registry_clear, registry_install,
61    registry_take,
62};
63pub use regs::ThreadRegs;
64pub use stack::{StackError, bootstrap_stack};
65pub use syscall::{
66    BsdSyscall, SyscallArgs, SyscallResult, known_syscalls, lookup as lookup_syscall, name_of,
67};
68pub use tls::{
69    GUEST_TLS_MAGIC, enter_host_tls, install_main_guest_tls, leave_host_tls, prepare_host_meta,
70};
71#[cfg(all(target_arch = "aarch64", target_os = "linux"))]
72pub use trap::kh_trampoline_dispatch;
73pub use trap::{
74    PSTATE_C, TrapConfig, TrapError, TrapEvent, TrapOutcome, clear_expect_code,
75    clear_trace_on_exit, finish_with_exit_code, hypercall_entry_addr, install_trap_handlers,
76    patch_svc_to_brk, set_expect_code, set_trace_on_exit, take_trace_events,
77};
78// `kh_hypercall_entry` is a `global_asm!` symbol; address via `hypercall_entry_addr`.