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

docs/u-boot.md: works on the phone, what the screen says, and what it took

shimoku747c28d91fccaa
diff --git a/docs/u-boot.md b/docs/u-boot.md
index 018da11..56104da 100644
--- a/docs/u-boot.md
+++ b/docs/u-boot.md
@@ -4,8 +4,8 @@ HakiOS's loader can be started by **Das U-Boot** instead of Project Silicium's U
U-Boot from RAM with `fastboot boot`, U-Boot finds the loader and its payload **in memory** and starts the loader as a UEFI
application. Nothing is flashed: not `boot`, not any other partition, and a reboot gives the phone back to Android.
-Status in one line: **works in QEMU (checked, the whole chain to the kernel's user space); built for the phone, not yet tried on
-it.** The sections below say exactly what was run.
+Status in one line: **works on the POCO X5 Pro and in QEMU, the whole chain to the kernel's user space, with `xl` as it was.**
+The sections below say exactly what was run.
## Why
@@ -92,7 +92,31 @@ fastboot continue # hakios boot
```
U-Boot's fastboot shows as Google's `18d1:4ee0` (the loader's own is `18d1:d00d`); `fastboot oem console` reads U-Boot's log.
-Hold **volume down** while U-Boot starts for its menu (start, fastboot, what is in memory, a shell over USB serial).
+Hold **volume down** while U-Boot starts for its menu (start, fastboot, what is in memory, a shell over USB serial): the volume
+keys move, the power key chooses.
+
+## What the screen says
+
+U-Boot writes what it does on the phone's screen, each line marked **`[oosexgang]`**: what the hakios command took and where it put
+it, and, once the loader talks to the host, the cable coming and going, every command of the host (the `getvar` polls of a run
+aside), every download and upload with its size, progress and speed, and every `FAIL` the loader answers:
+
+```
+[oosexgang] hakios: payload of 66216 bytes at 0xf0000000
+[oosexgang] usb: the host is connected
+[oosexgang] host: upload
+[oosexgang] sending 22 KiB
+[oosexgang] sent 22 KiB in 4 ms (5500 KiB/s)
+[oosexgang] host: oem screenshot
+[oosexgang] host: upload
+[oosexgang] sending 10125 KiB
+[oosexgang] 30%
+```
+
+(lines from the phone's screen after `xl run` and `xl screenshot`)
+
+`setenv hakios_status 0` (U-Boot's shell, or the environment file) turns it off. `hakios_usb_debug=1` shows much more: every
+control request, endpoint and transfer of the USB device protocol, which is how the faults below were found.
## Try it in QEMU (nothing of Apple's)
@@ -119,11 +143,38 @@ same way and gave the same.
## On the phone: what is known and what is not
-- U-Boot builds for `redwood` (`hakios_redwood_defconfig`), and the boot image is made the way Silicium's is, which ABL takes.
-- **Not yet run on the phone.** What is unknown until it is: that ABL starts it (U-Boot's Linux header instead of the shim's), that
- ABL's memory node is what U-Boot expects, that U-Boot's UFS driver brings the storage up after ABL, and that the DWC3 gadget
- enumerates (`dr_mode = "peripheral"`, high speed). If U-Boot hangs, the menu (volume down) and `fastboot oem console` are the
- ways in; [U-Boot's own notes on phones](https://docs.u-boot.org/en/latest/board/qualcomm/phones.html) say how to bisect a hang.
+Run on a POCO X5 Pro 5G (`redwood`, bootloader unlocked, Android on slot b), from Windows' platform-tools, 29 October 2026:
+
+- ABL starts the boot image with `fastboot boot`; U-Boot comes up on the panel, takes the size of RAM from ABL's device tree and
+ brings UFS up (SK hynix, six LUNs).
+- `./xl enter` (`XL_FIRMWARE` unset, no Silicium image): `xl: loader is up` in about 7 s. The loader finds the phone by its
+ framebuffer (`platform redwood`), arms its watchdog, and its fastboot answers (`product: xnuloader`, `version: 0.5`).
+- `./xl memmap`: every carve-out of the device tree reserved, the payload area as U-Boot's, and 5.4 GiB free above `0xF4000000`
+ for the kernel's window.
+- Ten `getvar` and 1 MiB `stage` in turn, all answered; the 16 MiB run payload in 0.55 s.
+- `XL_RAMDISK=prebuilt/userland/hello ./xl run`: the prebuilt kernel boots, `Hello from user space on Darwin!`, `initproc` exits
+ (that is what `hello` does) and the kernel returns: `result: returned 22037 0`. The loader's log is written to `logdump` and read
+ back the same.
+- `./xl screenshot`: the kernel's last screen, with U-Boot's `[oosexgang]` lines under it.
+- The way through U-Boot's own fastboot (`stage`, `oem run:hakios load fastboot`, `continue`): U-Boot takes the container and
+ starts the loader, but **the loader's USB then does not come up on the bus**: the controller, released by U-Boot's fastboot and
+ taken again by the loader, does not connect. Until that is fixed, put the loader and the payload in the boot image (`xl enter`
+ does).
+
+What it took on the phone, each seen there first (`hakios_usb_debug=1` and photographs of the screen):
+
+| Fault | Fix |
+|---|---|
+| The loader's descriptors (USB 2.10 and a BOS) promise Link Power Management, which U-Boot's DWC3 does not do: the device left the bus 3 s after it came | USB 2.0 and no BOS, as U-Boot's own gadgets |
+| U-Boot's endpoint autoconfig ORs the endpoint number into the address it is given (`0x01` became `0x03`) and writes a full-speed packet size (64) | only the direction goes in; the caller's packet size (512) comes back |
+| U-Boot's DWC3 starts a bulk transfer only on the XferNotReady the host's next token brings | it starts on queue, and the next one when one completes, as Linux's dwc3 |
+| U-Boot's DWC3 clears a stall with a transfer started (WinUSB clears the halt of a pipe it opens) | the transfer ends first and starts again after, as Linux's dwc3 |
+| `fastboot oem console`: every response dequeued a request that was not queued; the error went into the console it was sending, for ever | only a request in flight is dequeued |
+| The loader's log buffer was not aligned to the block size U-Boot's block I/O wants | aligned (`xnuloader/loader.c`) |
+| A download the host gave up half-way left the loader waiting for good | 20 s without a byte and it is given up |
+
+If U-Boot hangs, the menu (volume down) and `fastboot oem console` are the ways in;
+[U-Boot's own notes on phones](https://docs.u-boot.org/en/latest/board/qualcomm/phones.html) say how to bisect a hang.
- What the loader asks Qualcomm's UEFI for and U-Boot does not have: the charger protocols (the loader goes on without the battery
reading) and `EFI_CPU_ARCH_PROTOCOL` (the loader's exception hook is not installed; a fault in the loader resets the phone instead of
being logged).