Apple's open-source XNU kernel on Android phones: its own loader and drivers, Metal on the Adreno. Runs from RAM; a reboot gives the phone back to Android.
C
The loader answers the host while its kernel runs: stop, screenshot, log
vcvkk4fcc85d69bdd
diff --git a/README.md b/README.mdindex 9ae7ee6..6306bf7 100644--- a/README.md+++ b/README.md@@ -103,12 +103,15 @@ XL_SECS=900 XL_CMDLINE="touchscreen=1 cpufreq=1 bootcpu=7 cpus=4" ./xl run #самой системе, и заливается на 17 секунд быстрее; iOS при этом стартует секунды на две-три дольше.`./xl run` ждёт конца сеанса и кладёт журнал в `logs/`; запускать можно сколько угодно раз, образ системы в ОЗУ-остаётся. `./xl` без аргументов печатает все команды. Пока идёт сеанс, другие команды `xl` не выполняются-(«busy»): загрузчик отвечает одному собеседнику.+остаётся. `./xl` без аргументов печатает все команды. Пока идёт сеанс, из другого терминала работают+`./xl screenshot` (снимок экрана на ходу), `./xl log` (журнал ядра на данный момент), `./xl state` и+**`./xl stop`** — завершить сеанс сейчас. `XL_FOLLOW=5 ./xl run` каждые 5 секунд сохраняет журнал в+`logs/…-run.log.live`: если телефон сбросится без единого слова, останется всё, что ядро успело сказать.Управление как на iPhone X: свайп вверх от нижнего края — разблокировка и «домой», погасший экран будится-касанием. **Закончить сеанс раньше времени — приложить к экрану пять пальцев на полторы секунды**: ядро-вернётся в загрузчик (кнопки телефона под нашим ядром не опрашиваются).+касанием. **Закончить сеанс раньше времени — приложить к экрану пять пальцев на полторы секунды** (или+`./xl stop` с компьютера): ядро вернётся в загрузчик (кнопки телефона под нашим ядром не опрашиваются).+На экране при этом остаётся последний кадр.**Прочитайте до запуска:**diff --git a/prebuilt/SHA256SUMS b/prebuilt/SHA256SUMSindex 2def055..d8908c5 100644--- a/prebuilt/SHA256SUMS+++ b/prebuilt/SHA256SUMS@@ -1,7 +1,7 @@-Built 2026-10-12 17:24 from this tree.+Built 2026-10-12 17:38 from this tree.-24e5e728d670cbfcf73952d347df3c58777538c4070791b6588f4df1942c8ac0 prebuilt/mach.development.bcm2837-3fe61d8611217b8ae578f2bea50f7cb796a946d920a8c394805a46d1dda24318 prebuilt/loader.efi+4f1832f37e2ab7fcde0405cd8fd29f2dbb73716d89c2e394744fc3d7b92b9fc6 prebuilt/mach.development.bcm2837+1332a598d2dec00a1d8e930044e4f00a12ad44c6e5e50eecf4b7fe7fae803bf2 prebuilt/loader.efid2a35a4a1d6658ffb3696914f727661b52c9333de8a3af8a31642b8023ce03ac prebuilt/userland/child1a413befd511384052e1962c1394adce20f718e1f2657ce63ab09828ebc4bd1b prebuilt/userland/cpu_testdb564073effc31e7ab1679a7ffe0631ec22c3030ad347c927028f3e53c8583c3 prebuilt/userland/hellodiff --git a/prebuilt/loader.efi b/prebuilt/loader.efiindex 8c69a09..1c30f37 100755Binary files a/prebuilt/loader.efi and b/prebuilt/loader.efi differdiff --git a/prebuilt/mach.development.bcm2837 b/prebuilt/mach.development.bcm2837index 48a7999..fedb19a 100755Binary files a/prebuilt/mach.development.bcm2837 and b/prebuilt/mach.development.bcm2837 differdiff --git a/xl b/xlindex 5629a8c..9b84955 100755--- a/xl+++ b/xl@@ -6,11 +6,13 @@# xl ramdisk [FILE] upload the big system image (default userland/system.packfs) once; it stays in# the phone's RAM across kernel runs and is the root filesystem (/dev/md0)# ("xl ramdisk none" forgets it; the image sent with the kernel is then the root)-# xl screenshot [F] save what is in the phone's framebuffer as a PNG (default logs/screen.png)+# xl screenshot [F] save what is in the phone's framebuffer as a PNG (default logs/screen.png);+# works during a run too (from another terminal)# xl recording [F] fetch the screen recording the last run made (rec_secs=N among XL_CMDLINE) and# make a video of it (default logs/recording.mp4)# xl selftest exercise only the kernel->loader return path-# xl log fetch the loader's current log+# xl log fetch the loader's current log; during a run, the kernel's log so far as well+# xl stop end the run in progress now (the kernel returns as when its time is up)# xl hang watchdog test: make the loader hang on purpose# xl reboot cold-reset the phone (back to Android)# xl reload restart the phone into a freshly built loader (after changing xnuloader/)@@ -37,7 +39,10 @@ L=xnuloader/loader.efi[ -f $L ] || L=prebuilt/loader.efimkdir -p logs-fb() { timeout "${FB_TIMEOUT:-10}" fastboot "$@" 2>&1; }+# one fastboot at a time (a run in one terminal, "xl screenshot" in another): each takes the lock for itself+fb() { flock -w 90 logs/.xl.lock timeout "${FB_TIMEOUT:-10}" fastboot "$@" 2>&1; }+# does the loader answer while its kernel runs (0.5 and later)? an older one answers only when the run is over+live_loader() { fb getvar version | grep -Eq 'version: 0\.([5-9]|[1-9][0-9])'; }in_fastboot() { fastboot devices 2>/dev/null | grep -q fastboot; }is_loader() { in_fastboot && fb getvar product | grep -q 'product: xnuloader'; }state() {@@ -83,6 +88,8 @@ fetch_log() { # fetch_log <file>run() { # run <oem command> <label>enter || return 1+ exec 8> logs/.xl.run+ flock -n 8 || { echo "xl: a run is in progress (xl stop ends it)"; return 1; }local stamp log resultstamp=$(date +%H%M%S); log="logs/$stamp-$2.log"if [ "$1" != "oem selftest" ]; then@@ -96,8 +103,26 @@ run() { # run <oem command> <label>xnuloader/mkpayload.py -o run-payload.bin kernel=$K ${rd:+ramdisk=$rd} --cmdline "loader_return_after=${XL_SECS:-8} epoch=$(date +%s) sb_delay=${XL_SB_DELAY:-8} ${XL_CMDLINE--v}" >/dev/null || return 1FB_TIMEOUT=30 fb stage run-payload.bin | grep -q OKAY || { echo "xl: upload failed"; return 1; }fi+ local live=; live_loader && live=1fb $1 >/dev/null- result=$(FB_TIMEOUT=$(( ${XL_SECS:-8} + 100 )) fb getvar result | grep '^result:')+ if [ -n "$live" ] && [ "$1" != "oem selftest" ]; then+ # the loader goes on answering: ask every two seconds until the result is no longer "running".+ # XL_FOLLOW=N: fetch the log as it stands every N seconds as well, so that a phone that+ # resets without a word leaves all it said up to then ($log.live)+ local deadline=$(( $(date +%s) + ${XL_SECS:-8} + 100 )) followed=$(date +%s)+ while :; do+ result=$(FB_TIMEOUT=15 fb getvar result | grep '^result:')+ case "$result" in ""|*running*) ;; *) break ;; esac+ [ "$(date +%s)" -ge "$deadline" ] && { result=; break; }+ if [ -n "$XL_FOLLOW" ] && [ $(( $(date +%s) - followed )) -ge "$XL_FOLLOW" ]; then+ followed=$(date +%s)+ fb oem log | grep -q OKAY && fetch_log "$log.live"+ fi+ sleep 2+ done+ else+ result=$(FB_TIMEOUT=$(( ${XL_SECS:-8} + 100 )) fb getvar result | grep '^result:')+ fiif [ -z "$result" ]; thenecho "xl: no answer — the kernel hung; waiting for the watchdog to reset the phone"wait_for android 120 && echo "xl: phone is back in Android" || echo "xl: phone did not come back (state: $(state))"@@ -160,12 +185,13 @@ with open(out, 'wb') as f:PY}-# One command at a time: the loader answers one host at a time, and a second command sent while a-# run is waiting for its result ("xl state" in another terminal is enough) can cost that run its log.+# While a run is in progress the loader takes only what does not disturb the kernel: state, screenshot,+# log, stop, reboot. Anything else would wait for nothing.case "$1" in-"") ;;-*) exec 9> logs/.xl.lock- flock -n 9 || { echo "xl: busy: another xl command (a run?) is talking to the phone" >&2; exit 1; } ;;+""|run|selftest|state|screenshot|log|stop|reboot) ;;+*) if ! flock -n logs/.xl.run true 2>/dev/null; then+ echo "xl: a run is in progress: only state, screenshot, log, stop and reboot now" >&2; exit 1+ fi ;;esaccase "$1" in@@ -176,10 +202,11 @@ ramdisk) ramdisk "$2" ;;run) run "oem run $2" "run${2:+-cp$2}" ;;selftest) run "oem selftest" selftest ;;log) enter && fb oem log >/dev/null && fetch_log logs/loader.log && cat logs/loader.log ;;+stop) fb oem stop | grep -q OKAY && echo "xl: asked the kernel to come back" ;;memmap) enter && fb oem memmap >/dev/null && fb oem log >/dev/null && fetch_log logs/loader.log && sed -n '/^memory map/,$p' logs/loader.log ;;hang) enter && fb oem hang; echo "xl: waiting for the watchdog..."; t0=$(date +%s); wait_for android 150 && echo "xl: back in Android after $(( $(date +%s) - t0 )) s" || echo "xl: not back (state: $(state))" ;;reboot) fb reboot; ;;reload) [ "$(state)" = loader ] && { fb reboot >/dev/null; wait_for android 120; }; enter && echo "xl: loader is up" ;;state) state ;;-*) sed -n '2,23p' "$0" ;;+*) awk 'NR > 1 && /^#/ { print; next } NR > 1 { exit }' "$0" ;;esacdiff --git a/xnu/files/osfmk/arm64/loader_return.c b/xnu/files/osfmk/arm64/loader_return.cindex ea8b043..ed871e7 100644--- a/xnu/files/osfmk/arm64/loader_return.c+++ b/xnu/files/osfmk/arm64/loader_return.c@@ -146,6 +146,7 @@ struct loader_live {const bool *log_wrapped; /* the ring has gone round */uint64_t log_head, log_ring; /* sizes of the two parts */const uint64_t *recording; /* loader_recording: { physical address, length } of a screen recording */+ volatile uint64_t stop; /* the loader's to write: the host has asked for the run to end */};/*@@ -380,6 +381,37 @@ loader_return_timer_init(void)}STARTUP(EARLY_BOOT, STARTUP_RANK_LAST, loader_return_timer_init);+/*+ * A loader that watches from another core also listens to the host, and passes on a request to+ * end the run ("xl stop") by setting loader_live.stop. Look once a second.+ */+static thread_call_t loader_stop_call;++static void+loader_stop_poll(__unused thread_call_param_t p0, __unused thread_call_param_t p1)+{+ uint64_t deadline;++ if (loader_live.stop) {+ static const char banner[] = "\n--- the host asked for the end of the run: back to the loader ---\n";+ for (const char *c = banner; *c; c++) {+ loader_log_putc(*c);+ }+ loader_return();+ }+ clock_interval_to_deadline(1, NSEC_PER_SEC, &deadline);+ thread_call_enter_delayed(loader_stop_call, deadline);+}++__startup_func+static void+loader_stop_poll_init(void)+{+ loader_stop_call = thread_call_allocate(loader_stop_poll, NULL);+ loader_stop_poll(NULL, NULL);+}+STARTUP(EARLY_BOOT, STARTUP_RANK_LAST, loader_stop_poll_init);+/** boot-arg hv_wdt_pet=1: the loader has armed the Qualcomm hypervisor's* virtual watchdog (it resets the phone when a kernel hangs, so that testdiff --git a/xnuloader/loader.c b/xnuloader/loader.cindex fb5cbd2..9a03183 100644--- a/xnuloader/loader.c+++ b/xnuloader/loader.c@@ -780,6 +780,7 @@ struct kernel_live {uint64_t log, log_len, log_ring_at, log_wrapped; /* the kernel's virtual addresses: add the slide */uint64_t log_head, log_ring; /* the log: this much from the start of the boot, then a ring this big */uint64_t recording; /* (a virtual address too) { physical address, bytes } of a screen recording */+ uint64_t stop; /* ours to write: the host wants the run to end ("oem stop") */};/* The screen recording the last kernel left in memory, if it made one ("oem recording" stages it). */@@ -795,6 +796,14 @@ static uint64_t recording_len;static void wdt_pet(void);static int wdt_armed;+/*+ * While a kernel runs on another core and this one watches it: where it shows its signs of life,+ * for the commands that the host sends meanwhile (usb_poll_command).+ */+static const struct kernel_live *running_live;+static uint64_t running_slide;+static void usb_poll_command(void);+static uint64_tseconds_since(uint64_t then){@@ -839,6 +848,43 @@ log_of_hung_kernel(const struct kernel_live *live, uint64_t slide)}}+/*+ * The log of a kernel that is alive and is merely being asked how it is doing ("oem log" during+ * a run): a copy in the right order after the loader's own log, with nothing moved under the+ * kernel's feet.+ */+static void+compose_live_log(const struct kernel_live *live, uint64_t slide)+{+ static const char sep[] = "\n== KERNEL LOG (the kernel is still running) ==\n";+ const char *log = (const char *)(live->log + slide);+ uint32_t len = *(volatile uint32_t *)(live->log_len + slide);+ uint32_t ring_at = *(volatile uint32_t *)(live->log_ring_at + slide);+ int wrapped = *(volatile uint8_t *)(live->log_wrapped + slide);+ uint64_t n, room = sizeof(out_buf) - 8192;++ compose_logs(NULL, 0);+ n = staged_len;+#define PUT(from, size) do { \+ uint64_t take = (size); \+ if (n + take > room) { \+ take = room - n; \+ } \+ memcpy(out_buf + n, (from), take); \+ n += take; \+} while (0)+ PUT(sep, sizeof(sep) - 1);+ if (!wrapped || ring_at >= live->log_ring) {+ PUT(log, len <= live->log_head + live->log_ring ? len : live->log_head + live->log_ring);+ } else {+ PUT(log, live->log_head);+ PUT(log + live->log_head + ring_at, live->log_ring - ring_at);+ PUT(log + live->log_head, ring_at);+ }+#undef PUT+ staged_len = n;+}+static void print(const char *fmt, ...);static void flush_log(void);static void put_char(char c);@@ -909,6 +955,8 @@ run_on_other_cpu(uint64_t mpidr, uint64_t entry, uint64_t boot_args_pa, const stint64_t status;int arrived = 0, watching_only = 0;+ running_live = live;+ running_slide = slide;other_cpu_start.entry = entry;other_cpu_start.boot_args = boot_args_pa;other_cpu_stage = 0;@@ -991,9 +1039,11 @@ run_on_other_cpu(uint64_t mpidr, uint64_t entry, uint64_t boot_args_pa, const ststatus = OTHER_CPU_HUNG;}}+ usb_poll_command();for (volatile int i = 0; i < 20000; i++) {}}+ running_live = NULL;if (watching_only) {__asm__ volatile ("msr S3_0_C12_C12_7, %0\nisb" : : "r" (group1));@@ -2008,7 +2058,7 @@ usb_wait(uint8_t endpoint){/* static: a long transfer is many short waits, and the watchdog must be fed across them */static uint64_t last_pet;- uint64_t freq = READ_SYSREG(CNTFRQ_EL0);+ uint64_t freq = READ_SYSREG(CNTFRQ_EL0), began = READ_SYSREG(CNTVCT_EL0);for (;;) {uint32_t msg = UsbDeviceEventNoEvent;@@ -2020,6 +2070,10 @@ usb_wait(uint8_t endpoint)usb_connected = (data.device_state == UsbDeviceStateConnected);return -1;}+ /* with a kernel running, a host that went away must not keep this core from watching it */+ if (running_live != NULL && READ_SYSREG(CNTVCT_EL0) - began > 3 * freq) {+ return -1;+ }if (msg == UsbDeviceEventTransferNotification && data.transfer.endpoint_index == endpoint) {return data.transfer.status == UsbDeviceTransferStatusCompleteOK ? (int64_t)data.transfer.bytes_completed : -1;}@@ -2030,10 +2084,14 @@ usb_wait(uint8_t endpoint)}}+static int usb_rx_queued; /* usb_poll_command() has left the receive for the next command with the controller */+static int64_tusb_rx(uint8_t *buf, uint64_t len){- if (EFI_ERROR(USB->send(USB_EP_OUT, len, buf))) {+ if (usb_rx_queued) {+ usb_rx_queued = 0; /* (every command is received the same way, into the same buffer) */+ } else if (EFI_ERROR(USB->send(USB_EP_OUT, len, buf))) {return -1;}return usb_wait(USB_EP_OUT);@@ -2085,32 +2143,32 @@ starts_with(const char *s, const char *prefix)return 1;}+/*+ * One command from the host. While a kernel runs on another core (running_live) only what does+ * not disturb it: questions, the screen, the log so far, and "oem stop".+ */static void-usb_command_loop(void)+fb_command(char *cmd){- screen_quiet = 1;- for (;;) {- if (!usb_connected) {- usb_wait(0xff); /* returns on the next cable state change */- continue;- }- int64_t n = usb_rx(usb_rx_buf, 511);- if (n <= 0) {- continue;- }- char cmd[128];- if (n > (int64_t)sizeof(cmd) - 1) {- n = sizeof(cmd) - 1;- }- memcpy(cmd, usb_rx_buf, (size_t)n);- cmd[n] = 0;-- if (starts_with(cmd, "getvar:")) {+ int busy = running_live != NULL;++ {+ if (busy && (starts_with(cmd, "oem ramdisk") || starts_with(cmd, "download:") || starts_with(cmd, "oem run") ||+ starts_with(cmd, "oem selftest") || starts_with(cmd, "oem hang") || starts_with(cmd, "oem recording") ||+ starts_with(cmd, "oem clearscreen") || starts_with(cmd, "oem memmap"))) {+ fb_reply("FAIL", "a kernel is running (oem stop ends it)");+ } else if (starts_with(cmd, "oem stop")) {+ /* the kernel looks at this once a second and comes back as it does when its time is up */+ if (busy) {+ ((struct kernel_live *)(uintptr_t)running_live)->stop = 1;+ }+ fb_reply("OKAY", "");+ } else if (starts_with(cmd, "getvar:")) {const char *var = cmd + 7;if (str_eq(var, "product")) {fb_reply("OKAY", "xnuloader");} else if (str_eq(var, "version")) {- fb_reply("OKAY", "0.4");+ fb_reply("OKAY", "0.5");} else if (str_eq(var, "max-download-size")) {fb_reply("OKAY", download_to_ramdisk ? "0xffffffff" : "0x03f00000");} else if (str_eq(var, "result")) {@@ -2132,13 +2190,13 @@ usb_command_loop(void)if (starts_with(cmd, "oem ramdisk none")) {resident_rd_size = 0;fb_reply("OKAY", "");- continue;+ return;}parse_payload(&pi, 0);log_len = 0;if (!choose_window(&pi) || win_size <= RESIDENT_RD_OFFSET + RESIDENT_RD_RESERVE) {fb_reply("FAIL", "no memory window");- continue;+ return;}download_to_ramdisk = 1;fb_reply("OKAY", "");@@ -2156,7 +2214,7 @@ usb_command_loop(void)}if (total == 0 || total > limit) {fb_reply("FAIL", "bad size");- continue;+ return;}fb_reply_data(total);while (got < total) {@@ -2191,7 +2249,7 @@ usb_command_loop(void)/* stage the raw framebuffer; "getvar screen" gives its geometry */if (SCREEN.base == 0) {fb_reply("FAIL", "no display");- continue;+ return;}staged_data = (const char *)(uintptr_t)SCREEN.base;staged_len = (uint64_t)SCREEN.stride * SCREEN.height;@@ -2200,7 +2258,7 @@ usb_command_loop(void)/* stage what the kernel's display driver recorded (boot-arg rec_secs) */if (recording_data == NULL) {fb_reply("FAIL", "no recording");- continue;+ return;}staged_data = recording_data;staged_len = recording_len;@@ -2236,7 +2294,11 @@ usb_command_loop(void)print_memory_map();fb_reply("OKAY", "");} else if (starts_with(cmd, "oem log")) {- compose_logs(NULL, 0);+ if (busy) {+ compose_live_log(running_live, running_slide);+ } else {+ compose_logs(NULL, 0);+ }fb_reply("OKAY", "");} else if (starts_with(cmd, "reboot") || starts_with(cmd, "oem reboot")) {fb_reply("OKAY", "");@@ -2248,6 +2310,69 @@ usb_command_loop(void)}}+/*+ * A kernel is running on another core and this one watches it: see whether the host has said+ * something meanwhile, without waiting for it to. This is how a run can be asked to end, and+ * the screen and the log be had while it lasts.+ */+static void+usb_poll_command(void)+{+ uint32_t msg = UsbDeviceEventNoEvent;+ uint64_t size = 0, n;+ usb_device_event_data data;+ char cmd[128];++ if (USB == NULL) {+ return; /* this run was not started over USB */+ }+ if (!usb_rx_queued && usb_connected && !EFI_ERROR(USB->send(USB_EP_OUT, 511, usb_rx_buf))) {+ usb_rx_queued = 1;+ }+ USB->handle_event(&msg, &size, &data);+ if (msg == UsbDeviceEventDeviceStateChange) {+ usb_connected = (data.device_state == UsbDeviceStateConnected);+ usb_rx_queued = 0;+ return;+ }+ if (msg != UsbDeviceEventTransferNotification || data.transfer.endpoint_index != USB_EP_OUT) {+ return;+ }+ usb_rx_queued = 0;+ if (data.transfer.status != UsbDeviceTransferStatusCompleteOK || data.transfer.bytes_completed == 0) {+ return;+ }+ n = data.transfer.bytes_completed < sizeof(cmd) - 1 ? data.transfer.bytes_completed : sizeof(cmd) - 1;+ memcpy(cmd, usb_rx_buf, (size_t)n);+ cmd[n] = 0;+ fb_command(cmd);+}++static void+usb_command_loop(void)+{+ screen_quiet = 1;+ for (;;) {+ char cmd[128];+ int64_t n;++ if (!usb_connected) {+ usb_wait(0xff); /* returns on the next cable state change */+ continue;+ }+ n = usb_rx(usb_rx_buf, 511);+ if (n <= 0) {+ continue;+ }+ if (n > (int64_t)sizeof(cmd) - 1) {+ n = sizeof(cmd) - 1;+ }+ memcpy(cmd, usb_rx_buf, (size_t)n);+ cmd[n] = 0;+ fb_command(cmd);+ }+}+/* ------------------------------------------------------------------------ *//*