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: installing beside Android, for the person installing (dual-boot.md, ru/dual-boot.md); the rename's "Darwin userland 16.5 user space" said plainly

shimoku74ce29dfaa19fa
diff --git a/docs/air.md b/docs/air.md
index 95d7d06..6fc9f0d 100644
--- a/docs/air.md
+++ b/docs/air.md
@@ -996,7 +996,7 @@ Three references, each independent of the translator:
The other 98 of the 100 modules carried did not run, because the job list ended with
`/bin/sh /redwood/share/airops/run.sh` and the answer was
- **`/bin/sh: No such file or directory`, status 127. Darwin userland 16.5's own root has no shell at all**
+ **`/bin/sh: No such file or directory`, status 127. Darwin 16.5's own root has no shell at all**
— `/bin` holds `df` and `ps`, and nothing else. The `/var/jb/bin/sh` that `rc.jobs.jb` and
`rc.jobs.sileo` run belongs to the package manager's prefix, which only a `JB=1` image carries.
This was asserted, not checked: a `grep` for `bin/sh` matched six `rc.jobs*` files and the
diff --git a/docs/concepts/architecture.md b/docs/concepts/architecture.md
index b8d433c..b51168c 100644
--- a/docs/concepts/architecture.md
+++ b/docs/concepts/architecture.md
@@ -20,7 +20,7 @@ yours (the user space you lay out).
| 3. the loader | `xnuloader` reads the payload (the kernel, the command line, `kernel.ver`), lays out memory and the device tree the kernel expects, keeps a service for the storage, starts the kernel; at the end of a run it takes control back | `xnuloader/` |
| 4. the kernel | XNU with this port: Apple's patched files (`xnu/hakios.patch`), new ones (`xnu/files/`), the drivers (`drivers/`) | [Building](../getting-started/building.md) |
| 5. the drivers | each one does nothing until its boot-argument asks; those the configuration left out are not in the kernel at all | [Drivers in the configuration](../drivers-config.md) |
-| 6. user space | launchd starts what the system image holds: Darwin userland 16.5's (layer 2, yours), or `userland/hello` for the open kernel | `userland/` |
+| 6. user space | launchd starts what the system image holds: Darwin 16.5's (layer 2, yours), or `userland/hello` for the open kernel | `userland/` |
## How a configuration becomes a kernel and a command line
diff --git a/docs/dual-boot.md b/docs/dual-boot.md
new file mode 100644
index 0000000..8881ac7
--- /dev/null
+++ b/docs/dual-boot.md
@@ -0,0 +1,115 @@
+# Installing beside Android
+
+HakiOS on the POCO X5 Pro (redwood) as a second system: Android stays where it is, and at every start a menu asks which
+one to run. This page is for the person installing it. How it works underneath, and every step as it was first done and
+checked, is in [U-Boot](u-boot.md).
+
+| | |
+|---|---|
+| Started by | HakiOS's U-Boot in `boot_a`; it takes the loader and the kernel from memory |
+| The system | the partition `darwin`, 20 GiB at the end of LUN 0 |
+| Your data | HFS Plus, journaled, about 12 GB, kept between starts |
+| Android | slot b, untouched |
+
+## Before you start
+
+You need an unlocked bootloader, a computer with `fastboot` and `adb`, and a USB cable. The system's images come from
+your own copy of the firmware: none of it is in the repositories.
+
+**The installation erases Android's data.** `darwin` is cut from the end of `userdata`, and `fastboot -w` follows. Keep
+a copy of what you need, and keep the partition backup of step 1 off the phone.
+
+## Install
+
+1. **Back up the partitions.** From Android, as root: both slots' boot partitions, `vbmeta*`, `persist`, `modemst1/2`,
+ the first and last blocks of every unit. Without this copy a broken partition table cannot be put back.
+
+ ```sh
+ python3 tools/backup-partitions.py --yes
+ ```
+
+2. **Make `darwin`.** `userdata` is shortened and `darwin` (20 GiB) made at the end of LUN 0; then Android's data is
+ erased.
+
+ ```sh
+ python3 tools/userdata-carve.py --wipe backups 20
+ fastboot -w
+ ```
+
+3. **Write the system volume.** The system volume and the two cryptexes from your firmware go to the start of `darwin`.
+ Google's `fastboot` for Windows runs out of memory on one 8 GB image, so it is cut into pieces flashed one after the
+ other.
+
+ ```sh
+ python3 tools/sparse-split.py darwin.img pieces
+ fastboot flash darwin pieces/piece-00.simg # and every other piece
+ ```
+
+4. **Make the data volume.** An empty HFS Plus volume in the rest of `darwin`. The image is about 50 KB and leaves the
+ system volume alone. Flashing it again empties the data volume.
+
+ ```sh
+ python3 tools/mkdatavol.py data.simg
+ fastboot flash darwin data.simg
+ ```
+
+5. **Install the boot image.** U-Boot, the loader and the kernel in `boot_a`, slot a made active: the menu comes up at
+ the next start.
+
+ ```sh
+ fastboot flash boot_a hakios-install.img
+ fastboot set_active a
+ fastboot reboot
+ ```
+
+## The menu
+
+The menu waits 10 seconds. With no choice it starts Android: under HakiOS the phone does not charge, so a phone that
+restarts by itself is better off in Android. The volume keys move, the power key chooses.
+
+| Entry | What it does |
+|---|---|
+| Android (the default) | marks slot a unbootable and restarts; ABL makes Android's slot active |
+| HakiOS (Darwin) | starts the system from memory |
+| HakiOS over fastboot | waits for a new kernel from the computer (development) |
+| Fastboot | the phone's bootloader |
+| What is in memory | what is loaded, and which slot is active |
+| U-Boot shell | U-Boot's command line |
+| Reset | restarts |
+
+After Android is chosen, slot b is active and the phone starts straight into Android. To have the menu again:
+`fastboot set_active a`, or, in Android with root, the service `hakios-menu.sh` (`devices/redwood/u-boot/android/`),
+which does it after every boot.
+
+## Your data
+
+`/private/var` is the HFS Plus volume in `darwin`, right after the system: about 12 GB, kept between starts, and
+replayed from its journal after a sudden power-off. If it does not mount, the system starts on a memory volume
+instead: empty at every start, and Settings shows about 1 GB.
+
+The first start on a new volume is the slowest: the system registers its applications and sets up its data. Until it
+has finished, some icons and the wallpaper may be missing.
+
+## What works
+
+| Part | State | |
+|---|---|---|
+| Display, touch, the interface | works | drawn by the Adreno 642L through OpenGL ES |
+| Data volume | works | HFS Plus, about 12 GB, kept |
+| Wi-Fi | partly | started with `wifi=1` |
+| Graphics effects | partly | the renderer lacks some of the functions a few effects use |
+| Sound, vibration | off | they stop the phone when started under U-Boot |
+| Cellular | no | the modem starts; nothing uses it yet |
+| Charging | no | charge in Android |
+
+## When it goes wrong
+
+**A black screen or a hang.** Hold volume down and power until fastboot appears. From there, Android:
+`fastboot set_active b`, then `fastboot reboot`.
+
+**"Device Error" for every image.** ABL found the slots' attributes and the partitions' types out of step. Do not flash
+another phone's partition table: put back your own from step 1, then `fastboot set_active` to the slot that works. The
+whole recovery, step by step, is in [U-Boot](u-boot.md#which-slot-is-active-is-never-u-boots-to-change).
+
+**What happened.** The loader writes the log of every start to the partition `logdump`; on the computer, `./xl log`
+fetches it.
diff --git a/docs/index.md b/docs/index.md
index e6427b1..61c9d82 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -6,11 +6,12 @@ of Apple's and nothing of any phone's.
Where to start:
-- [Getting started](getting-started/index.md): the open kernel in QEMU in a few commands, or the Darwin userland 16.5 user space you lay
+- [Getting started](getting-started/index.md): the open kernel in QEMU in a few commands, or the Darwin 16.5 user space you lay
out yourself.
- [On the phone](getting-started/phone.md): the POCO X5 Pro 5G, in RAM with `fastboot boot`, back to Android with a reboot.
- [Port a device](porting/index.md): a device is a repository of its own over the common one: a defconfig, a status file, its
drivers.
+- [Installing beside Android](dual-boot.md): HakiOS as a second system on the POCO X5 Pro, a menu at every start, your data kept.
- [U-Boot](u-boot.md): the loader started by U-Boot instead of Silicium's UEFI, from RAM, with nothing of the vendor's.
- [Reference](reference/drivers.md): every driver, configuration symbol and boot argument, made from the source.
@@ -34,7 +35,7 @@ The table is made from the devices' own `device.conf`: [all devices](devices/ind
## The three layers
1. **The open core**: the kernel port, the loader, the drivers, the tools. All source, in these repositories.
-2. **What you put on top**: the kernel can start a user space you supply; it was built so that it can start Darwin userland 16.5's, which you
+2. **What you put on top**: the kernel can start a user space you supply; it was built so that it can start Darwin 16.5's, which you
lay out yourself from Apple's own download. None of it is in the repositories.
3. **Apple's services** (activation, Apple ID, iCloud, the App Store): not supported and not a goal.
diff --git a/docs/metal-plan.md b/docs/metal-plan.md
index 3562e4d..c25e99d 100644
--- a/docs/metal-plan.md
+++ b/docs/metal-plan.md
@@ -107,7 +107,7 @@ How it was checked, and what that does not show:
`_MTLDevice`, `_MTLResource`, `_MTLLibrary`, `_MTLFunction`: buffers written, read back, copied, refused over `maxBufferLength`,
freed (and the caller's deallocator called); the five Darwin libraries read (36, 135, 11, 274 and 0 functions; the last is
SafariSharedUI's, a header and nothing else), every function made by its name with its type, every module LLVM bitcode. All
- under the address sanitizer. **macOS's Metal is not Darwin userland 16.5's**: this shows the plug-in's own logic, not that Darwin's Metal is
+ under the address sanitizer. **macOS's Metal is not Darwin 16.5's**: this shows the plug-in's own logic, not that Darwin's Metal is
content with these objects.
- Built for Darwin userland 16.5 (`-Wall -Wextra`, no warnings). Not yet run on Darwin: `metal_test` asks "what the device makes" in a process of
its own (`RC_JOBS=rc.jobs.metal`, `metal=1`), and its line is the result that goes here.
@@ -129,13 +129,13 @@ it is in this repository, the facts below are written here in our own words and
the question of the next step, and it is not decided here.
- **Universal metallibs.** Newer systems ship framework libraries as a fat container (0xCAFEBABE) of an AIR64 slice and a binary
for Apple's GPUs (QuartzCore's `default.metallib` on iPadOS 17). `hakios_metallib_thin()` takes the AIR64 slice, as Metal does;
- `tools/metallib-test.sh` and `tools/metal-plugin-test.sh` check it. Darwin userland 16.5's libraries are all thin.
+ `tools/metallib-test.sh` and `tools/metal-plugin-test.sh` check it. Darwin 16.5's libraries are all thin.
- **CoreImage's limits.** `CIMetalDeviceGetLimits` reads `dedicatedMemorySize` and `sharedMemorySize`, which `_MTLDevice` does
not answer; without them every `CIContext` throws (iconservicesagent ended over symbol glyphs there). The device now answers
them, `isLowPower`, `isRemovable`, `isHeadless`, and `supportsFeatureSet:` (NO: the base reads Apple's tables).
- **Clients by a file.** A file beside the bundle names the processes shown the device. `HakiosMetal.clients` does the same here,
on top of `metal=N`.
-- **The window server needs QuartzCore's own `default.metallib`.** Their system image has it; Darwin userland 16.5's (this port's) does not,
+- **The window server needs QuartzCore's own `default.metallib`.** Their system image has it; Darwin 16.5's (this port's) does not,
which is the wall of step 7 above. It is not something the plug-in can supply: the library is Apple's.
## Frame skips
diff --git a/docs/ru/dual-boot.md b/docs/ru/dual-boot.md
new file mode 100644
index 0000000..86c0a4e
--- /dev/null
+++ b/docs/ru/dual-boot.md
@@ -0,0 +1,113 @@
+# Установка рядом с Android
+
+HakiOS на POCO X5 Pro (redwood) второй системой: Android остаётся на месте, а при каждом включении меню спрашивает, что
+запускать. Эта страница для того, кто устанавливает. Как это устроено внутри и как каждый шаг был впервые сделан и
+проверен — в [U-Boot](../u-boot.md).
+
+| | |
+|---|---|
+| Запуск | U-Boot от HakiOS в `boot_a`; загрузчик и ядро он берёт из памяти |
+| Система | раздел `darwin`, 20 ГиБ в конце LUN 0 |
+| Ваши данные | HFS Plus с журналом, около 12 ГБ, сохраняются между запусками |
+| Android | слот b, без изменений |
+
+## Перед началом
+
+Нужны разблокированный загрузчик, компьютер с `fastboot` и `adb` и кабель USB. Образы системы берутся из вашей копии
+прошивки: в репозиториях их нет.
+
+**Установка стирает данные Android.** `darwin` вырезается из конца `userdata`, затем нужен `fastboot -w`. Сохраните всё
+нужное, а копию разделов из шага 1 держите вне телефона.
+
+## Установка
+
+1. **Резервная копия разделов.** Из Android с root: загрузочные разделы обоих слотов, `vbmeta*`, `persist`,
+ `modemst1/2`, первые и последние блоки каждого LUN. Без этой копии испорченную таблицу разделов не вернуть.
+
+ ```sh
+ python3 tools/backup-partitions.py --yes
+ ```
+
+2. **Раздел `darwin`.** `userdata` укорачивается, в конце LUN 0 создаётся `darwin` на 20 ГиБ, затем данные Android
+ стираются.
+
+ ```sh
+ python3 tools/userdata-carve.py --wipe backups 20
+ fastboot -w
+ ```
+
+3. **Системный том.** Системный том и два криптекса из вашей прошивки записываются в начало `darwin`. Windows-версия
+ `fastboot` не справляется с образом на 8 ГБ, поэтому он режется на части, которые прошиваются по очереди.
+
+ ```sh
+ python3 tools/sparse-split.py darwin.img pieces
+ fastboot flash darwin pieces/piece-00.simg # и так каждую часть
+ ```
+
+4. **Том для данных.** Пустой том HFS Plus в оставшейся части `darwin`. Образ весит около 50 КБ и не трогает системный
+ том. Повторная прошивка стирает данные.
+
+ ```sh
+ python3 tools/mkdatavol.py data.simg
+ fastboot flash darwin data.simg
+ ```
+
+5. **Загрузочный образ.** U-Boot, загрузчик и ядро — в `boot_a`, слот a становится активным: при следующем включении
+ появится меню.
+
+ ```sh
+ fastboot flash boot_a hakios-install.img
+ fastboot set_active a
+ fastboot reboot
+ ```
+
+## Меню
+
+Меню ждёт 10 секунд. Если ничего не выбрать, запускается Android: под HakiOS телефон не заряжается, и после
+самопроизвольной перезагрузки ему лучше оказаться в Android. Кнопки громкости — выбор, кнопка питания — подтверждение.
+
+| Пункт | Что делает |
+|---|---|
+| Android (по умолчанию) | помечает слот a неготовым и перезагружает; ABL делает активным слот Android |
+| HakiOS (Darwin) | запускает систему из памяти |
+| HakiOS over fastboot | ждёт новое ядро с компьютера (для разработки) |
+| Fastboot | загрузчик телефона |
+| What is in memory | что загружено и какой слот активен |
+| U-Boot shell | командная строка U-Boot |
+| Reset | перезагрузка |
+
+После выбора Android активен слот b, и телефон сразу загружается в Android. Чтобы меню вернулось:
+`fastboot set_active a` или, в Android с root, служба `hakios-menu.sh` (`devices/redwood/u-boot/android/`), которая
+делает это после каждой загрузки.
+
+## Ваши данные
+
+`/private/var` — это том HFS Plus в `darwin`, сразу за системой: около 12 ГБ, сохраняется между запусками,
+восстанавливается по журналу после внезапного отключения. Если он не смонтировался, система запустится на томе в памяти:
+он пуст при каждом включении, и в настройках видно около 1 ГБ.
+
+Первый запуск на новом томе самый долгий: система регистрирует приложения и готовит данные. Пока она не закончила, части
+значков и обоев может не быть.
+
+## Что работает
+
+| Часть | Состояние | |
+|---|---|---|
+| Экран, касания, интерфейс | работает | рисует Adreno 642L через OpenGL ES |
+| Том данных | работает | HFS Plus, около 12 ГБ, сохраняется |
+| Wi-Fi | частично | включается с `wifi=1` |
+| Графические эффекты | частично | рендереру не хватает части функций для некоторых эффектов |
+| Звук, вибрация | выключено | при запуске через U-Boot роняют телефон |
+| Сотовая связь | нет | модем запускается, но им пока ничто не пользуется |
+| Зарядка | нет | заряжайте в Android |
+
+## Если что-то пошло не так
+
+**Чёрный экран или зависание.** Зажмите громкость вниз и питание, пока не появится fastboot. Оттуда в Android:
+`fastboot set_active b`, затем `fastboot reboot`.
+
+**«Device Error» при любой загрузке.** ABL нашёл, что атрибуты слотов не совпадают с типами разделов. Не прошивайте
+таблицу разделов с другого телефона: верните свою из шага 1, затем `fastboot set_active` на рабочий слот. Всё
+восстановление по шагам — в [U-Boot](../u-boot.md#which-slot-is-active-is-never-u-boots-to-change).
+
+**Что произошло.** Загрузчик пишет журнал каждого запуска в раздел `logdump`; на компьютере его забирает `./xl log`.