Skip to content

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.md
index 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/SHA256SUMS
index 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.efi
d2a35a4a1d6658ffb3696914f727661b52c9333de8a3af8a31642b8023ce03ac prebuilt/userland/child
1a413befd511384052e1962c1394adce20f718e1f2657ce63ab09828ebc4bd1b prebuilt/userland/cpu_test
db564073effc31e7ab1679a7ffe0631ec22c3030ad347c927028f3e53c8583c3 prebuilt/userland/hello
diff --git a/prebuilt/loader.efi b/prebuilt/loader.efi
index 8c69a09..1c30f37 100755
Binary files a/prebuilt/loader.efi and b/prebuilt/loader.efi differ
diff --git a/prebuilt/mach.development.bcm2837 b/prebuilt/mach.development.bcm2837
index 48a7999..fedb19a 100755
Binary files a/prebuilt/mach.development.bcm2837 and b/prebuilt/mach.development.bcm2837 differ
diff --git a/xl b/xl
index 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.efi
mkdir -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 result
stamp=$(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 1
FB_TIMEOUT=30 fb stage run-payload.bin | grep -q OKAY || { echo "xl: upload failed"; return 1; }
fi
+ local live=; live_loader && live=1
fb $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:')
+ fi
if [ -z "$result" ]; then
echo "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 ;;
esac
case "$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" ;;
esac
diff --git a/xnu/files/osfmk/arm64/loader_return.c b/xnu/files/osfmk/arm64/loader_return.c
index 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 test
diff --git a/xnuloader/loader.c b/xnuloader/loader.c
index 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_t
seconds_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 st
int64_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 st
status = 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_t
usb_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);
+ }
+}
+
/* ------------------------------------------------------------------------ */
/*