Skip to content

Latest commit

 

History

History
168 lines (138 loc) · 13.4 KB

index.md

File metadata and controls

168 lines (138 loc) · 13.4 KB

HakiOS

Apple's open-source Darwin kernel (XNU) on Android phones, the way Android is Linux on phones: a boot loader of its own, drivers of its own, a configuration system and a version of its own. The same kernel runs in QEMU with nothing of Apple's and nothing of any phone's.

Where it stands. The POCO X5 Pro 5G runs the Darwin 16.5 user space you lay out yourself, and its window server draws through Metal on the Adreno 642L, at 100 to 104 frames a second in page swipes on a 120 Hz panel. 120 has not been reached: the measurements.

Guide: run it

Page What
Getting started three ways in, and what your machine needs
QEMU the open kernel in a few commands, or the Darwin user space you lay out yourself
On the phone the POCO X5 Pro 5G, in RAM with fastboot boot, back to Android with a reboot
Windows the same from a Windows PC: what runs in WSL 2, what in Git Bash; a measured Metal run
Installing beside Android HakiOS as a second system, a menu at every start, your data kept (in Russian)
Building from source when you change something

Porting: bring a device

Page What
Port a device a device is a repository of its own over the common one: a defconfig, a status file, its drivers
How the repositories fit common, SoC, device, UEFI, and the manifest that names them
Writing a driver a driver as an option of the kernel's own configuration
Drivers in the configuration CONFIG_HAKIOS_*, and how a choice reaches XNU
Bring-up on a PKG110 a phone that reports another brand: what was checked on it, and how

Drivers and GPU: what each does, and how far

Page What
Metal on the Adreno the two Metal paths compared: interfaces, build, boot arguments, how to measure, known gaps
Metal measurements what the phone did, in numbers, and what did not help
Metal plan how it got here, step by step
The shader compiler, its report Apple's shader bitcode into the Adreno's code
Metal, why and where the wall is the first analysis, in Russian
Development notes the old README, whole: the history of the work, in Russian
Devices how far each part works, device by device: redwood, QEMU
Cellular the modem's bring-up (in Russian)
GNSS the S9's BCM4775 GNSS: what its firmware holds (an on-chip position engine), the tools, the next steps
gnssd the GNSS chain into iOS: the chip's bring-up, locationd's gpsd protocol (and the one change to locationd), the GPS app's status
telephonyd CoreTelephony's server without CommCenter: the two services, what it answers ("no SIM"), the seam for the modem's kern.hakios.cellular_*
Driver reviews each driver read for what it does and what was and was not verified
Network review the network stack, read the same way

Concepts: how it fits together

Page What
Architecture the three programs between a phone's firmware and a user space; what is written to the phone
Configuration defconfigs and fragments, like Linux's
Versioning a version string that says what it is built from
UEFI boot, U-Boot the two firmwares that can start the loader
Installing: the design, safely what installing means here, and what it must never do

Reference: look something up

Page What
Drivers every driver, made from the source
Boot arguments every argument any part of the system reads, made from the source
Commands make targets and the scripts below them

The project

Page What
Changelog what changed, newest first
Comparison HakiOS next to the other XNU-on-a-phone projects
Legal review, LEGAL, compliance, third parties what is and is not distributed, and what is still to verify
Contributing, community how to take part
The site the installer's guide as one web page

Scion's own pages

  • Android beside iOS on the Galaxy S9: a design for the S9, a boot chooser, a partition plan and a write fence. Nothing run on a phone.
  • U-Boot: the loader started by U-Boot instead of Silicium's UEFI, from RAM, with nothing of the vendor's.
  • A modular kernel: how this tree maps onto UniXNU's layers, what is ours in XNU, OS profiles.
  • The kernel's architecture: its layers, what may depend on what, the conventions of a driver of several files, and how a file is split without changing the kernel; the census of the large files and their splits.
  • Two XNU bases: xnu-8796 (iOS 16.5) and xnu-12377 (iOS 26) in one tree; the profile, series and device layout; what may be taken from ios-on-pixel-10.
  • Apps without an App Store account: web apps on the home screen from the first boot (WEBCLIPS=1), what open-source iOS apps can be built from source and run on a phone at iOS 16.5, and the plan for push.
  • iOS 27 on a Galaxy S9: build it and install it yourself: what you need, the commands from your own restore image to the home screen, what works, what does not, how to get back. It erases the phone.
  • Moving iOS 27 on the Galaxy S9 to another iOS build: everything tied to 24A446, what 27.2.1 (24B156) is likely to change, the build manifests of tools/ios27/builds/, the steps, the disk and the effort.
  • iOS 27 on the Galaxy S9: why it does not boot yet (kernel, CPUs, the builder's inputs), what iOS 27 asks of the kernel, and Darwin 27's system calls on xnu-12377.
  • The real key store: keystore_real=1, off by default: the keychain's keys under the passcode, what that does and does not protect from, and what it costs.
  • Screen-off power: what the Galaxy S9 does with its screen off, and panel_sleep=1, sleep_cores=1 (off by default).
  • The passcode: Settings' passcode and the lock screen, on a key store with no Secure Enclave (it locks the screen, it does not encrypt), and how to get back in (passcode_reset=1).
  • Face ID, studied: what Face ID is made of on iOS 27, what the Galaxy S9 can offer in its place, and why Scion offers a passcode and will not present anything as Face ID.
  • The iris camera: why the Galaxy S9's infrared iris camera's frames never reach memory (Samsung keeps them in the secure world), with the evidence from Samsung's kernel.
  • The iris scanner through Samsung's own trusted application: whether Scion could ask Samsung's iris TA, through its normal interface, to enrol and match; the verdict, what must be proven in which order, and the owner's decisions (a study).

What works

As each device's own device.conf records it: all devices. Where the Metal row is ahead of a device's file, the measurements are the source. The rows about the lock screen and the apps describe what happens when you add layer 2 below yourself.

POCO X5 Pro 5G (redwood) QEMU virt
Lock screen, home screen, Control Center, the stock apps yes yes (slow: the CPU is emulated)
Touch, multitouch, buttons yes yes (the mouse and the keyboard)
All 8 CPU cores, the big one at 2.4 GHz yes no
GPU (OpenGL ES through Mesa) yes no
Metal partly: the window server draws through it, on two paths (Metal), off by default; swipes 100 to 104 frames a second, not 120; other programs not shown partly: a device Metal loads; no GPU, nothing drawn; on the S9's Mali-G72 through PanVK, not Adreno: metal.md
Wi-Fi yes yes (virtio-net)
Sound, microphone yes sound only (virtio)
The battery's level yes no
Cameras, vibration yes no
/private/var kept across reboots, Sileo, SSH yes no
Flashlight, temperature guard partly: written, some of it seen (redwood) no
Cellular partly: the modem is up, the SIM bound, the network seen; no registration yet (cellular) no
Bluetooth, charging under this kernel, Apple's services no no

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 that you supply. It was built so that it can start the Darwin 16.5 user space, which you lay out yourself from files you download from Apple; nothing of it is shipped, and nothing is circumvented to get it. Whether you may do that, and whether you want to, is your decision.
  3. Apple's services (activation, Apple ID, iCloud, the App Store): not supported and not a goal.

By default the loader goes into RAM through fastboot boot, the system lives in RAM for a session, and a reboot brings the phone back to its own Android. The one thing written by default is the loader's own log (a few KB) to the logdump partition; with ufs_write=1 the kernel writes only to a partition darwin that you create yourself. What is and is not written to a phone: Architecture.

What is in the repository, and what never is

In it: only our own code and data: our changes to Apple's open-source XNU (the fork Scion-Project/xnu, APSL 2.0) and our files, the boot loader, our programs and libraries, the tools, prebuilt/ (built from this source; the loader without any Apple data: make loader makes the one that starts Darwin, on your machine, from your own IPSW), and the device and SoC directories. Third parties' files and patches to their code are listed with their licenses in THIRD_PARTY_LICENSES.md.

Never in it: any file of Darwin (you build the system image on your machine from an IPSW you get yourself and hand to sysimage/unpack.sh; nothing is downloaded for you, decrypted or circumvented); the phone's firmware (pulled from your own phone into fw-*/, which git ignores); keys, certificates, activation, or anything that would make the phone pass as an iPhone to Apple.

The core kernel, the boot loader and the open tools build and run with nothing of Apple's: make qemu-open is the open kernel, a placeholder loader and a tiny raw-syscall user space, in QEMU, with no IPSW, no Darwin user space and no firmware. Booting the stock Darwin user space (make qemu, make phone) is an optional path that needs the IPSW and the phone's firmware, which you supply from your own device. Licenses: the XNU patch under the Apple Public Source License 2.0, the terms met as COMPLIANCE.md says; the rest as the file headers say. None of this is legal advice.

The repositories

Repository What
scion-kernel common: the kernel port, every common driver, the loader, user space, the tools, this documentation, and devices/qemu
hakios-metal/ Metal's command model on the Adreno, through the kernel's GPU driver (HakiOS's, taken into this tree)
hakios-sm7325 POCO X5 Pro 5G: its defconfig, status, UEFI platform, firmware script, and its SoC's layer (soc/: the Qualcomm SC7280 family)
hakios-mt6768 Infinix Hot 20 (MediaTek Helio G85): an experimental port with its own loader; not in devices/manifest.conf
hakios-uefi the firmware that starts the loader: Mu-Silicium with HakiOS's boot path, banner and name, and HakiOS's U-Boot (u-boot/)
hackios-web the website, which carries a copy of these pages
hackios-xnu-userland old: a pointer. User space is userland/ in the common repository

devices/manifest.conf in the common repository names the device and UEFI repositories and the revision each is at; tools/hakios-device.py sync clones them into devices/ and uefi/. One repository per device: it carries its SoC's layer, and tools/hakios-device.py new makes one from the phone's own device tree, with every phone driver left out until it is ported. Each driver is an option of the kernel's own configuration (CONFIG_HAKIOS_*, XNU's options and conf/files), so a device's defconfig builds exactly the drivers it has. How the repositories fit.