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, tools: UEFI boot and installation, said honestly; doctor looks at what an install would stand on

shimoku4dd1af720883
diff --git a/docs/install.md b/docs/install.md
new file mode 100644
index 0000000..40fa8a3
--- /dev/null
+++ b/docs/install.md
@@ -0,0 +1,68 @@
+# Installing HakiOS on a phone: the design, and what is missing
+
+**Nothing in this document has been run on a phone.** The pieces it names exist and are tested one by one (in QEMU,
+against stand-in programs, by their own self-tests). The whole chain has not been tried, and the attached phone was
+not on USB while this was written. Read it as the safety model that an install has to meet, not as instructions.
+
+## Today
+
+HakiOS is booted from RAM: `./xl enter` takes a boot image with `fastboot boot`, and a reboot brings Android back.
+Android's own partitions are not written. The one default write is the loader's log (a few KB) into the phone's
+`logdump` partition at the end of a run, and with `ufs_write=1` the kernel may write to the port's own partition
+`darwin` and nowhere else. The complete list of what can write is in `tools/provenance.allow` (the `flash` lines), and
+CI fails if another writer appears.
+
+## What "installed" would mean
+
+Android stays, HakiOS sits beside it and is chosen at boot, and going back is a slot switch. Two things have to live
+on the phone:
+
+1. **The boot chain.** The boot image `./xl enter` builds (`mkxnuimg.py`: Project Silicium's UEFI, the shim and a
+ payload) already starts with no host: the shim puts the payload in memory and the loader runs it, in one-shot mode
+ when the payload carries no `usb` entry. Installed, that same kind of image would sit in the boot partition of the
+ **inactive** slot.
+2. **The system.** The partition `darwin`, cut off the end of Android's userdata once
+ (`tools/userdata-carve.py` prints the plan and says what it does to Android's data), written by
+ `tools/darwin-write.py`, which refuses everything but that partition and reads every write back. The root image for
+ it is the flash recipe (`FLASHBOOT=1 userland/build.sh`).
+
+`make doctor` already looks at what this stands on, read only: whether the phone reports two slots, which one Android
+runs from, and whether `darwin` exists.
+
+## Rules an install must keep
+
+Each one is how the project already treats writes (`darwin-write.py`, the loader's refusals), carried over:
+
+1. **Look before anything is written, and keep what was there.** Slots, partition table and free space are read first;
+ before a write, the partitions that will be touched, the GPT head and tail and the boot and `vbmeta` partitions
+ are copied off the phone and hashed twice.
+2. **Only the inactive slot.** Never the slot Android runs from. No A/B, no install.
+3. **Never the partitions that cannot be made again**: the bootloader chain, the modem's and radio's calibration, and
+ the phone's own identity data.
+4. **Every write is read back and compared**, and a mismatch stops everything.
+5. **A way back that does not need this host**: choosing Android's slot again, with the standard `fastboot set_active`.
+6. **Dry run by default.** Each step is printed with the checks it made, one at a time; a person types the
+ confirmation for each; nothing is done on a script's own say-so.
+7. **Everything is logged**, refusals too.
+
+## What exists and what does not
+
+| Needed | State |
+|---|---|
+| A boot image that starts with no host (shim + payload) | exists (`mkxnuimg.py`); the loader started from it by `fastboot boot` on the attached phone |
+| A guarded writer for `darwin` | exists (`tools/darwin-write.py`); its self-test refuses the wrong partition |
+| A plan for carving `darwin` | exists (`tools/userdata-carve.py`, prints the commands, writes nothing) |
+| Read-only preflight | exists (`make doctor`): slots, `darwin`, firmware, root, bootloader as reported |
+| **Writing the boot image to a slot and switching to it** | **not done, not tried** |
+| **Booting the flash recipe's root from `darwin`** | **not verified** (the arguments it needs are not confirmed) |
+| **Project Silicium's Boot Manager behaving the same from a boot slot** | **unknown** |
+| **Verified boot (`vbmeta`) for a modified boot image** | **unknown** |
+| An installer that chains the steps under the rules above | not written |
+
+## Why there is no installer yet
+
+A wrong write can leave a phone that does not boot, and an unlocked bootloader only makes the mistake possible, not
+recoverable. An installer that has never been run on a phone, written without one on the desk, would be a guess
+with a progress bar. What can be built and checked first is built and checked: the read-only preflight, the guarded
+writer, the plans. The slot step comes when a phone is attached, a spare slot is confirmed, backups exist and a
+person is watching.
diff --git a/docs/uefi-boot.md b/docs/uefi-boot.md
new file mode 100644
index 0000000..0fcddd2
--- /dev/null
+++ b/docs/uefi-boot.md
@@ -0,0 +1,61 @@
+# UEFI boot
+
+HakiOS can start the way a UEFI operating system starts: the firmware runs `\EFI\BOOT\BOOTAA64.EFI` from a volume,
+that loader reads the kernel from the same volume, and nothing else is needed: no fastboot, no host computer.
+
+Status in one line: **works in QEMU (checked); not tried on a phone.** The sections below say exactly what was run.
+
+## Three ways a payload reaches the loader
+
+The payload is what the loader starts: the kernel, a small root image, the command line and `kernel.ver`
+(`xnuloader/mkpayload.py`). The loader takes a payload that is already in memory first, and looks on the volume
+only when there is none.
+
+| Way | How | Where | Checked |
+|---|---|---|---|
+| `fastboot boot` | `./xl enter`: a boot image holding Project Silicium's UEFI, a shim and the payload; the shim copies the payload to `0xF0000000` | the phone | yes: the loader started on the attached phone, its banner was read back from the screen and from the log |
+| a loader device | QEMU's `-device loader` puts the payload at `0xF0000000` (`make qemu-open`) | QEMU | yes |
+| **a file of the volume** | the loader opens the volume it was started from and reads `\EFI\hakios\payload.bin` itself | any UEFI that starts the loader from a volume | **in QEMU only** (AAVMF) |
+
+## The volume
+
+```
+EFI/BOOT/BOOTAA64.EFI the loader, where an AArch64 UEFI boots a removable volume from
+EFI/hakios/payload.bin the payload
+EFI/hakios/kernel.ver the version, as text, for a person to read
+```
+
+`make esp` makes the tree in `build/esp` (`tools/mkesp.py`, which refuses what the loader would refuse: not a payload,
+no kernel in it, over 63 MiB, a loader that is not an EFI application, a directory that is not empty). Copy it to a
+FAT32 volume, or serve it to QEMU.
+
+## Try it (QEMU, nothing of Apple's closed software: `make doctor` first)
+
+```sh
+make qemu-open # builds the kernel, the open loader, hello, and boots them (the payload device)
+QEMU_ESP=1 qemu/run.sh 90 # the same payload, but as the file \EFI\hakios\payload.bin: no loader device
+make esp # the tree for a real volume: build/esp
+```
+
+What `QEMU_ESP=1` prints under the banner: `payload: 15306944 bytes from \EFI\hakios\payload.bin on the volume this
+loader was started from`, then the kernel boots and `hello` reads the same version through `sysctl kern.hakios.version`.
+A file that is not a payload gives `is not a payload (no XNUP at its start)`, and no file gives `there is no
+\EFI\hakios\payload.bin on the volume`, each with `kernel.ver=unknown` and no crash (both were run).
+
+## Limits
+
+- **63 MiB.** The loader's payload region is 64 MiB and its last MiB holds the panic log. The kernel is about 15 MiB;
+ the **big iOS system image (2.5 GB) does not come this way**. It comes over USB (`xl ramdisk`, once per loader
+ session) or, in the flash recipe, from the partition `darwin` (`docs/install.md`).
+- **The region has to be free.** The loader takes it with `AllocatePages(AllocateAddress)`. A firmware that keeps it
+ reserved refuses, and the loader says so and goes on without a payload, as it always did.
+- **Nothing is signed.** The loader is not signed and no Secure Boot is involved.
+
+## On a phone: what is known and what is not
+
+- Project Silicium's Boot Manager, in this port, is changed to start the XNU loader **from the container the shim
+ leaves in memory instead of a menu** (`devices/poco-x5-pro/uefi/README.md`). It does not look for a loader on a
+ volume. So the file-of-the-volume way has **not** been tried on the phone, and it needs a change to the Boot
+ Manager (or a UEFI that boots from a volume) before it can be.
+- Whether Silicium leaves `0xF0000000` free at the point where the loader runs is not known.
+- The way to a phone that does not need a host today is the boot image itself, in a boot slot: `docs/install.md`.
diff --git a/tools/doctor.sh b/tools/doctor.sh
index 026b39b..1b83e71 100644
--- a/tools/doctor.sh
+++ b/tools/doctor.sh
@@ -135,6 +135,21 @@ else
note "bootloader as reported: locked=$lk verifiedboot=$vb (root-hiding modules can fake this; the real test is ./xl enter)"
bat=$(A 'cat /sys/class/power_supply/battery/capacity')
if [ -n "$bat" ] && [ "$bat" -lt 30 ] 2>/dev/null; then warn "battery $bat%" "charge it: HakiOS does not charge the phone while it runs"; else ok "battery ${bat:-?}%"; fi
+
+ # What a persistent install would stand on (docs/install.md). Only looked at: nothing here writes to the phone.
+ slot=$(A 'getprop ro.boot.slot_suffix')
+ if [ -n "$slot" ]; then
+ ok "A/B slots: Android runs from slot ${slot#_}; a persistent install would use the other slot and leave Android on this one"
+ else
+ warn "no A/B slot suffix reported" "a persistent install keeps Android on one slot and HakiOS on the other: without two slots there is no safe place for it (docs/install.md)"
+ fi
+ if [ "$root" = 1 ]; then
+ if A 'su -c "ls /dev/block/by-name"' | grep -qx darwin; then
+ ok "the partition darwin exists (the port's own: persistence and the iOS system image)"
+ else
+ note "no partition darwin yet: only persistence and a flash install need it (tools/userdata-carve.py plans it, and says what it does to Android's data)"
+ fi
+ fi
fi
fi