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

README in Ukrainian and Chinese

shimoku74d4823e9cb1c2
diff --git a/.gitignore b/.gitignore
index 50e0864..0711cfc 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,6 +4,8 @@
/*
!/.gitignore
!/README.md
+!/README.uk.md
+!/README.zh.md
!/Makefile
!/LICENSE
!/LICENSE.APSL
diff --git a/README.md b/README.md
index 6ef0513..2316e60 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,7 @@
# HakiOS
+English · [中文](README.zh.md) · [Українська](README.uk.md)
+
HakiOS runs the open-source XNU kernel (xnu-8796.121.2) with my own boot loader and my own drivers
on an Android phone with a Qualcomm SoC, and boots the stock iOS 16.5 user space on top of it:
launchd, backboardd, SpringBoard, the apps. The same thing runs in QEMU (`virt`, aarch64) on a
diff --git a/README.uk.md b/README.uk.md
new file mode 100644
index 0000000..e99aba6
--- /dev/null
+++ b/README.uk.md
@@ -0,0 +1,128 @@
+# HakiOS
+
+[English](README.md) · [中文](README.zh.md) · Українська
+
+HakiOS запускає відкрите ядро XNU (xnu-8796.121.2) з власним завантажувачем і власними драйверами
+на Android-телефоні з процесором Qualcomm, а поверх нього — стандартний користувацький простір
+iOS 16.5: launchd, backboardd, SpringBoard, застосунки. Те саме працює в QEMU (`virt`, aarch64)
+на звичайному комп'ютері з Linux.
+
+Нічого не прошивається. Завантажувач іде в ОЗП через `fastboot boot`, система живе в ОЗП до кінця
+сеансу, а перезавантаження повертає телефон у його власний Android. Це дослідницький стенд, а не
+прошивка.
+
+Перший телефон — **POCO X5 Pro 5G** (`redwood`, Snapdragon 778G). Ядро нічого не знає про нього
+наперед: кожна адреса, переривання, лінія живлення і прошивка беруться з дерева пристроїв самого
+телефона та його Android, тож порт на інший телефон Qualcomm — це новий каталог у `devices/`, а
+не переписування.
+
+## Що є в репозиторії
+
+Лише мій код і мої дані:
+
+- ядро: патч до відкритого XNU від Apple (`xnu/redwood.patch`, APSL 2.0) і мої файли драйверів
+ (`xnu/files/`), які `xnu/apply.sh` накладає на свіжий клон;
+- завантажувач (`xnuloader/`), мої програми й бібліотеки (`userland/src/`), інструменти
+ (`tools/`), скрипти збірки та запуску;
+- `prebuilt/`: ядро, завантажувач і бібліотеки, зібрані з цього репозиторію;
+- `devices/redwood/`: те, що потрібно одному телефону (порт UEFI, дерево пристроїв, скрипт прошивок).
+
+Чого немає і не буде:
+
+- жодного файлу iOS: ні бінарників, ні образів, ні кешів, ні шрифтів, ні картинок, ні знімків
+ екрана. Образ системи ви збираєте на своїй машині з IPSW iOS 16.5, який `sysimage/fetch.sh`
+ завантажує з публічних серверів Apple, нічого не розшифровуючи й не обходячи;
+- прошивок телефона (GPU, Wi-Fi, аудіо-DSP, модем, вібро, камери): вони вендорські і знімаються
+ з вашого власного телефона в `fw-*/`, які git ігнорує;
+- ключів, сертифікатів, активації чи будь-чого, що видавало б телефон за iPhone перед службами
+ Apple. Вхід в обліковий запис Apple тут неможливий і не є метою.
+
+## Стан
+
+| Працює | Ще ні |
+|---|---|
+| Екран блокування, домашній екран, Пункт керування, жести, стандартні застосунки | Стільниковий зв'язок: модем стартує, бачить мережу, SIM прив'язана; реєстрація та палички в статус-барі — у роботі (`docs/cellular.md`) |
+| Сенсорний екран, мультитач, кнопки живлення та гучності | Bluetooth |
+| Усі 8 ядер процесора, велике ядро на 2,4 ГГц | Заряджання під цим ядром |
+| Графіка на Adreno (`gpu=1`, OpenGL ES через Mesa) | Metal (є компілятор шейдерів, самого Metal немає) |
+| Динаміки й мікрофон (`adsp=1 sound=4 mic=4`) | Обліковий запис Apple: немає Secure Enclave |
+| Рівень батареї в інтерфейсі (через аудіо-DSP, `adsp=1`) | |
+| Вібрація (`haptic=5`) | |
+| Wi-Fi: радіо, драйвер, підключення до мережі (`wifi=1`) | |
+| Камери в Camera.app (`cam=5`) | |
+| `/private/var` зберігається між перезавантаженнями (`var_store=1 ufs_write=1`) | |
+| Sileo, пакети Procursus, SSH на телефон | |
+
+## Швидкий старт у QEMU
+
+Linux x86-64, близько 12 ГБ на диску, 7-Zip 23 або новіший, `lz4`, `qemu-system-aarch64`, `edk2-aarch64`.
+
+```sh
+git clone https://github.com/oosexgang/hackios-xnu-kernel.git hakios
+cd hakios
+make fetch # IPSW iOS 16.5 із серверів Apple, потрібне розпаковується (7,4 ГБ)
+make images # образи APFS: userland/root.apfs і userland/system.apfs
+make qemu # сеанс на 20 хвилин
+```
+
+Екран блокування з'являється за дві-три хвилини. Миша з затиснутою кнопкою — палець; `H` —
+«Додому», `L` — кнопка живлення, `↑`/`↓` — гучність.
+
+## На телефоні
+
+Телефон, для якого є порт (`devices/redwood/`, POCO X5 Pro 5G), з розблокованим завантажувачем,
+`adb` і `fastboot` на комп'ютері, образи з попереднього розділу і прошивки самого телефона:
+
+```sh
+make firmware # GPU, Wi-Fi, звук/батарея, вібро, модем, камери -> fw-*/
+make phone # 10-хвилинний сеанс з усім залізом, потім назад в Android
+make phone ARGS="modem=1" SECS=300 # або свій набір параметрів ядра
+```
+
+Головні параметри ядра (повний список — у `docs/ru/notes.md`):
+
+| Параметр | Що дає |
+|---|---|
+| `cpus=8 bootcpu=7 cpufreq=1` | усі ядра процесора та їхні частоти |
+| `touchscreen=1` | сенсорний екран |
+| `gpu=1` | малювання на Adreno (образ, зібраний з `GL=1`, прошивки у `fw-gpu/`) |
+| `adsp=1 sound=4 mic=4` | аудіо-DSP: динаміки, мікрофон; з ним же батарея та заряджання |
+| `haptic=5` | вібромотор |
+| `wifi=1` | Wi-Fi (мережа з `fw-wifi/network`) |
+| `cam=5` | камери |
+| `modem=1` | модем поруч із системою: його прошивка, файлові системи, IPA, SIM, NAS |
+| `var_store=1 ufs_write=1` | зберігати `/private/var` між перезавантаженнями |
+
+## Збірка з вихідників
+
+```sh
+make kernel # XNU з GitHub Apple + мої зміни -> xnu-src/, залежності, збірка
+make loader # завантажувач; identity.h робиться при збірці з вашого IPSW
+make images # користувацький простір і образи
+```
+
+Подробиці: `xnu/README.md`, `docs/ru/notes.md`.
+
+## Структура
+
+| Каталог | Вміст |
+|---|---|
+| `xnu/` | патч і файли ядра; `apply.sh`, `export.sh`; README про ядро |
+| `xnu/files/bsd/dev/redwood_*.c` | мої драйвери: екран, тач, UFS, GPU, Wi-Fi, звук, модем, SIM/NAS, вібро, камери |
+| `xnuloader/` | завантажувач (застосунок UEFI) |
+| `userland/` | мої програми й бібліотеки (`src/`), збірка образів, завдання launchd |
+| `sysimage/` | скрипти, що беруть і розпаковують файли ОС з IPSW (самих файлів немає) |
+| `devices/redwood/` | один телефон: його порт UEFI, дерево пристроїв, готові образи UEFI, скрипт прошивок |
+| `tools/` | APFS, прошивки, тести QMI, скрипти прогонів |
+| `qemu/` | запуск у QEMU |
+| `docs/` | `cellular.md` — зв'язок (англійською); `ru/` — докладний щоденник розробки російською |
+| `prebuilt/` | зібрані ядро, завантажувач, бібліотеки |
+
+## Ліцензії та юридична сторона
+
+Мій код — під ліцензією тих файлів, які він змінює: патч XNU — Apple Public Source License 2.0
+(повний текст у `LICENSE.APSL`; умови дотримано: зміни опубліковано у вихідниках, повідомлення
+збережено), решта — MIT (`LICENSE`). iOS, її образи, торгові марки Apple і прошивки телефона
+належать їхнім власникам, у репозиторій не входять і мною не поширюються; кожен бере їх зі свого
+телефона та свого IPSW. Сторонні компоненти перелічено в `NOTICE`. Якщо, на вашу думку, якийсь
+файл тут порушує чиїсь права — відкрийте issue, і я його приберу.
diff --git a/README.zh.md b/README.zh.md
new file mode 100644
index 0000000..5a6b8d3
--- /dev/null
+++ b/README.zh.md
@@ -0,0 +1,121 @@
+# HakiOS
+
+[English](README.md) · 中文 · [Українська](README.uk.md)
+
+HakiOS 在搭载高通 SoC 的 Android 手机上运行开源的 XNU 内核(xnu-8796.121.2),配上我自己写的引导
+程序和驱动,并在其上启动原版 iOS 16.5 用户空间:launchd、backboardd、SpringBoard 和各个应用。同样
+的东西也能在 Linux 电脑上的 QEMU(`virt`,aarch64)里运行。
+
+不刷写任何东西。引导程序通过 `fastboot boot` 进入内存,系统在内存里运行一个会话,重启后手机回到
+它自己的 Android。这是一个研究用的试验台,不是 ROM。
+
+第一台手机是 **POCO X5 Pro 5G**(`redwood`,骁龙 778G)。内核事先对它一无所知:每个地址、中断、
+电源轨和固件都来自手机自己的设备树和它的 Android,所以移植到另一台高通手机意味着在 `devices/`
+下新建一个目录,而不是重写。
+
+## 仓库里有什么
+
+只有我的代码和我的数据:
+
+- 内核:对 Apple 开源 XNU 的补丁(`xnu/redwood.patch`,APSL 2.0)和我的驱动文件(`xnu/files/`),
+ 由 `xnu/apply.sh` 叠加到一份新克隆上;
+- 引导程序(`xnuloader/`)、我的程序和库(`userland/src/`)、工具(`tools/`)、构建和运行脚本;
+- `prebuilt/`:用本仓库构建出的内核、引导程序和库;
+- `devices/redwood/`:一台手机所需的东西(UEFI 移植、设备树、固件脚本)。
+
+永远不会有的东西:
+
+- 任何 iOS 文件:没有二进制、镜像、缓存、字体、图片或截图。系统镜像由你在自己机器上用 iOS 16.5
+ 的 IPSW 构建,`sysimage/fetch.sh` 从 Apple 的公开服务器为你下载它,不解密、不绕过任何东西;
+- 手机的固件(GPU、Wi-Fi、音频 DSP、调制解调器、振动、摄像头):属于厂商,从你自己的手机取到
+ `fw-*/`,git 忽略这些目录;
+- 密钥、证书、激活,或任何让手机在 Apple 服务面前冒充 iPhone 的东西。这里无法登录 Apple 账户,
+ 这也不是目标。
+
+## 现状
+
+| 可用 | 尚未 |
+|---|---|
+| 锁屏、主屏、控制中心、手势、系统自带应用 | 蜂窝网络:调制解调器已启动、能看到网络、SIM 已绑定;注册和状态栏信号格正在进行(`docs/cellular.md`) |
+| 触摸屏、多点触控、电源和音量键 | 蓝牙 |
+| 全部 8 个 CPU 核心,大核 2.4 GHz | 本内核下的充电 |
+| Adreno GPU 渲染(`gpu=1`,经 Mesa 的 OpenGL ES) | Metal(有着色器编译器,没有 Metal) |
+| 扬声器和麦克风(`adsp=1 sound=4 mic=4`) | Apple 账户:没有 Secure Enclave |
+| 界面里的电池电量(经音频 DSP,`adsp=1`) | |
+| 振动(`haptic=5`) | |
+| Wi-Fi:射频、驱动、联网(`wifi=1`) | |
+| 相机应用里的摄像头(`cam=5`) | |
+| `/private/var` 跨重启保留(`var_store=1 ufs_write=1`) | |
+| Sileo、Procursus 软件包、SSH 登录手机 | |
+
+## QEMU 快速开始
+
+Linux x86-64,约 12 GB 磁盘,7-Zip 23 或更新,`lz4`,`qemu-system-aarch64`,`edk2-aarch64`。
+
+```sh
+git clone https://github.com/oosexgang/hackios-xnu-kernel.git hakios
+cd hakios
+make fetch # 从 Apple 服务器取 iOS 16.5 IPSW,解包所需部分(7.4 GB)
+make images # APFS 镜像:userland/root.apfs 和 userland/system.apfs
+make qemu # 20 分钟的会话
+```
+
+两三分钟后出现锁屏。按住鼠标键就是手指;`H` 是主屏键,`L` 是电源键,`↑`/`↓` 是音量。
+
+## 在手机上
+
+一台有移植的手机(`devices/redwood/`,POCO X5 Pro 5G),已解锁引导程序,电脑上有 `adb` 和
+`fastboot`,上一节的镜像,以及手机自己的固件:
+
+```sh
+make firmware # GPU、Wi-Fi、音频/电池、振动、调制解调器、摄像头 -> fw-*/
+make phone # 10 分钟会话,全部硬件开启,然后回到 Android
+make phone ARGS="modem=1" SECS=300 # 或自定义内核参数
+```
+
+主要内核参数(完整列表见 `docs/ru/notes.md`):
+
+| 参数 | 作用 |
+|---|---|
+| `cpus=8 bootcpu=7 cpufreq=1` | 全部 CPU 核心及其频率 |
+| `touchscreen=1` | 触摸屏 |
+| `gpu=1` | Adreno 渲染(镜像需以 `GL=1` 构建,固件在 `fw-gpu/`) |
+| `adsp=1 sound=4 mic=4` | 音频 DSP:扬声器、麦克风;电池与充电也经由它 |
+| `haptic=5` | 振动马达 |
+| `wifi=1` | Wi-Fi(网络来自 `fw-wifi/network`) |
+| `cam=5` | 摄像头 |
+| `modem=1` | 与系统并行启动调制解调器:固件、文件系统、IPA、SIM、NAS |
+| `var_store=1 ufs_write=1` | 跨重启保留 `/private/var` |
+
+## 从源码构建
+
+```sh
+make kernel # 从 Apple 的 GitHub 取 XNU 源码 + 我的修改 -> xnu-src/,依赖,构建
+make loader # 引导程序;identity.h 在构建时由你的 IPSW 生成
+make images # 用户空间和镜像
+```
+
+详情见 `xnu/README.md` 和 `docs/ru/notes.md`。
+
+## 目录结构
+
+| 目录 | 内容 |
+|---|---|
+| `xnu/` | 内核补丁和文件;`apply.sh`、`export.sh`;内核 README |
+| `xnu/files/bsd/dev/redwood_*.c` | 我的驱动:显示、触摸、UFS、GPU、Wi-Fi、音频、调制解调器、SIM/NAS、振动、摄像头 |
+| `xnuloader/` | 引导程序(UEFI 应用) |
+| `userland/` | 我的程序和库(`src/`)、镜像构建、launchd 任务 |
+| `sysimage/` | 从 IPSW 取得并解包系统文件的脚本(不含文件本身) |
+| `devices/redwood/` | 一台手机:UEFI 移植、设备树、预构建 UEFI 镜像、固件脚本 |
+| `tools/` | APFS、固件、QMI 测试、运行脚本 |
+| `qemu/` | 在 QEMU 中运行 |
+| `docs/` | `cellular.md`:蜂窝网络(英文);`ru/`:详细的俄文开发日志 |
+| `prebuilt/` | 构建好的内核、引导程序、库 |
+
+## 许可与法律
+
+我的代码遵循它所修改文件的许可:XNU 补丁为 Apple Public Source License 2.0(全文在
+`LICENSE.APSL`;条款已满足:修改以源码形式发布,保留了声明),其余为 MIT(`LICENSE`)。iOS、
+其镜像、Apple 商标和手机固件属于各自的所有者,不在本仓库中,也不由我分发;每个人从自己的手机和
+自己的 IPSW 取得它们。第三方组件列于 `NOTICE`。若你认为这里的某个文件侵犯了任何人的权利,请开一
+个 issue,我会删除它。