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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.shindex 026b39b..1b83e71 100644--- a/tools/doctor.sh+++ b/tools/doctor.sh@@ -135,6 +135,21 @@ elsenote "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+ fififi