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.


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

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.
```
python3 tools/backup-partitions.py --yes
```
Make darwin. userdata is shortened and darwin (20 GiB) made at the end of LUN 0; then Android's data is erased.
```
python3 tools/userdata-carve.py --wipe backups 20
fastboot -w
```
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.
```
python3 tools/sparse-split.py darwin.img pieces
fastboot flash darwin pieces/piece-00.simg     # and every other piece
```
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.
```
python3 tools/mkdatavol.py data.simg
fastboot flash darwin data.simg
```
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.
```
fastboot flash boot_a hakios-install.img
fastboot set_active a
fastboot reboot
```

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.

What happened. The loader writes the log of every start to the partition logdump; on the computer, ./xl log fetches it.

#Installing beside Android

#Before you start

#Install

#The menu

#Your data

#What works

#When it goes wrong