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

Drivers chosen by the defconfig, repositories per SoC and device, HakiOS UEFI, documentation

shimoku4e8cb2aeb5bb
diff --git a/.gitignore b/.gitignore
index d4fcabb..de348c3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -20,6 +20,8 @@
!/COMPLIANCE.md
!/THIRD_PARTY_LICENSES.md
!/devices/
+!/socs/
+!/uefi/
!/drivers/
!/docs/
!/xl
@@ -102,7 +104,7 @@ __pycache__/
!/xnuloader/mkidentity.sh
# the phone vendor's UEFI drivers, and the UEFI image built with them: proprietary, so never tracked. They
-# stay on the disk of whoever extracted them from their own phone (devices/redwood/uefi/README.md).
+# stay on the disk of whoever extracted them from their own phone (uefi/README.md).
/devices/*/uefi/files/Binaries/*/*
!/devices/*/uefi/files/Binaries/*/README.md
/devices/*/prebuilt/SILICIUM_UEFI.fd
diff --git a/Makefile b/Makefile
index 9853988..5427714 100644
--- a/Makefile
+++ b/Makefile
@@ -18,8 +18,10 @@
# to copy to a FAT32 volume (UEFI-native boot, no fastboot; docs/uefi-boot.md)
#
# Configuration, the way Linux's make does it (configs/, tools/hakios-config.py; docs/configs.md):
-# make redwood_defconfig .config from configs/defconfig + redwood_defconfig, which is common_defconfig + sc7280.config + redwood.config
+# make redwood_defconfig .config from configs/defconfig + redwood_defconfig (devices/redwood/configs/), which is
+# common_defconfig + sc7280.config (socs/sc7280/) + redwood.config
# (any NAME_defconfig; make common_defconfig is the common kernel alone; docs/configs.md)
+# make devices the device and SoC repositories (tools/hakios-device.py list; docs/porting/repositories.md)
# make virt.config lay a fragment (configs/virt.config) over the .config there is
# make config show the .config: its symbols, the kernel's arguments, the firmware it wants
# make savedefconfig the .config as a minimal defconfig
@@ -48,7 +50,7 @@ IMAGE_OPTS ?= REST=1
ESP_DIR ?= build/esp
PAYLOAD ?= qemu/payload.bin
-.PHONY: help fetch images kernel loader loader-open hello qemu qemu-open phone prebuilt clean all doctor defconfig config savedefconfig esp
+.PHONY: devices help fetch images kernel loader loader-open hello qemu qemu-open phone prebuilt clean all doctor defconfig config savedefconfig esp
help:
@awk '{ if (!/^#/) exit; sub(/^# ?/, ""); print }' Makefile
@@ -113,6 +115,9 @@ esp:
defconfig:
tools/hakios-config.py defconfig defconfig $(FRAGMENTS)
+devices:
+ @tools/hakios-device.py list
+
%_defconfig:
tools/hakios-config.py defconfig $* $(FRAGMENTS)
diff --git a/README.md b/README.md
index d1dcd88..a121ca9 100644
--- a/README.md
+++ b/README.md
@@ -2,192 +2,86 @@
English · [中文](README.zh.md) · [Українська](README.uk.md)
-HakiOS is an adaptation of the Darwin kernel (Apple's open-source XNU, xnu-8796.121.2) to Android phones with a
-Qualcomm SoC, in the way Android is an adaptation of Linux to phones: my own boot loader, my own drivers, a
-configuration system (`configs/`) and a kernel version of its own (`VERSION`). The same thing runs in QEMU
-(`virt`, aarch64) on a Linux PC, with nothing of Apple's and nothing of any phone's (`make qemu-open`).
-
-It has three layers, and the project says which one it stands behind (`LEGAL.md`):
-
-1. **The open core**: the kernel port, the loader, the drivers, the tools. All source, in this repository.
-2. **What you put on top**: the kernel can start a user space that you supply. The project was built so that it can
- start the iOS 16.5 user space, which you lay out yourself from files you download from Apple; it ships none of it
- and circumvents nothing to get it. Whether you may do that, and whether you want to, is your decision.
+**Apple's open-source Darwin kernel (XNU, xnu-8796.121.2) on Android phones with a Qualcomm SoC**, 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 (`make qemu-open`).
+
+**Documentation: [docs/](docs/index.md)**, also on the project's website (`hakios-web`). Start with [Getting started](docs/getting-started/index.md), [Port a device](docs/porting/index.md) or the
+[Architecture](docs/concepts/architecture.md).
+
+## What works
+
+| | 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 |
+| All 8 CPU cores, the big one at 2.4 GHz | yes | no |
+| GPU rendering on Adreno (OpenGL ES through Mesa) | yes | no |
+| Speakers, microphone, the battery's level | yes | sound only |
+| Wi-Fi, cameras, vibration | yes | network only |
+| `/private/var` kept across reboots, Sileo, SSH | yes | no |
+| Metal | partly: a device Metal loads; buffers and libraries; nothing drawn yet | partly |
+| Cellular | partly: the modem is up, the SIM bound, the network seen; no registration yet | no |
+| Bluetooth, charging under this kernel, Apple's services | no | no |
+
+Every part, as each device's own `device.conf` records it: [Devices](docs/devices/index.md). The rows about the lock screen and the
+apps describe what happens when you add layer 2 below yourself.
+
+## 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 iOS 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 the length of a session,
-and a reboot brings the phone back to its own Android. The one thing it writes by default is its own log (a few KB)
-to the phone's `logdump` partition; with `ufs_write=1` the kernel writes only to a partition `darwin` that you
-create yourself. This is a research bench, not a ROM.
-
-More: [`COMMUNITY.md`](COMMUNITY.md) (the community and the token, and what they are not), [`docs/configs.md`](docs/configs.md)
-(defconfigs and fragments), [`docs/versioning.md`](docs/versioning.md) (`kernel.ver`), [`docs/boot-args.md`](docs/boot-args.md)
-(every boot argument), [`docs/uefi-boot.md`](docs/uefi-boot.md), [`docs/install.md`](docs/install.md) (the design of an install,
-not an installer), [`docs/comparison.md`](docs/comparison.md) (the other projects), [`drivers/README.md`](drivers/README.md).
-
-The first phone is the **POCO X5 Pro 5G** (`redwood`, Snapdragon 778G). The kernel knows nothing
-about it in advance: every address, interrupt, power rail and firmware comes from the phone's own
-device tree and its own Android, so a port to another Qualcomm phone is a new directory under
-`devices/`, not a rewrite.
-
-## What is in the repository
-
-Only my code and my data:
-
-- the kernel: a patch to Apple's open-source XNU (`xnu/hakios.patch`, APSL 2.0) and my driver
- files (`xnu/files/`, `drivers/`), laid over a fresh clone by `xnu/apply.sh`;
-- the boot loader (`xnuloader/`), my programs and libraries (`userland/src/`), tools (`tools/`),
- build and run scripts;
-- `prebuilt/`: the kernel, loader and libraries built from this repository (the loader is built **without** any Apple data: `make loader` makes the one that starts iOS, on your machine, from your own IPSW);
-- `devices/redwood/`: what one phone needs (its UEFI port, device tree, firmware script).
-
-Not in the repository, never:
-
-- any file of iOS: no binary, image, cache, font, picture or screenshot. You build the system
- image on your machine from the iOS 16.5 IPSW, which `sysimage/fetch.sh` downloads from Apple's
- public servers for you, without decrypting or circumventing anything;
-- the phone's firmware (GPU, Wi-Fi, audio DSP, modem, haptics, cameras): it is the vendor's and
- is 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's services. Signing in to an Apple account is impossible here and not a goal.
-
-## Status
+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. This is a research bench, not a ROM.
-The rows about the lock screen, the apps and so on describe what happens when you add layer 2 yourself.
-
-| Works | Not yet |
-|---|---|
-| Lock screen, home screen, Control Center, gestures, the stock apps | Cellular: the modem boots, sees the network, the SIM is bound, the IPA data path and `en1` are in place; registration, the data session and the status bar bars are in progress (`docs/cellular.md`) |
-| Touch screen, multitouch, power and volume buttons | Bluetooth |
-| All 8 CPU cores, the big core at 2.4 GHz | Charging under this kernel |
-| GPU rendering on Adreno (`gpu=1`, OpenGL ES through Mesa) | Metal (there is a shader compiler, no Metal) |
-| Speakers and microphone (`adsp=1 sound=4 mic=4`) | Apple account: no Secure Enclave |
-| Battery level in the UI (through the audio DSP, `adsp=1`) | |
-| Vibration (`haptic=5`) | |
-| Wi-Fi: radio, driver, network connection (`wifi=1`) | |
-| Cameras in Camera.app (`cam=5`) | |
-| `/private/var` kept across reboots (`var_store=1 ufs_write=1`) | |
-| Sileo, Procursus packages, SSH into the phone | |
-
-## Quick start in QEMU
-
-Linux x86-64, about 12 GB of disk, 7-Zip 23 or newer, `lz4`, `qemu-system-aarch64`, `edk2-aarch64`.
+## Quick start
```sh
-git clone https://github.com/oosexgang/hackios-xnu-kernel.git hakios
+git clone https://github.com/shimoku74/hakios.git hakios
cd hakios
-make doctor # what this machine lacks (QEMU's display device, UEFI firmware, memory), and what to do
-sysimage/fetch.sh # the iOS 16.5 IPSW from Apple's servers, the needed parts unpacked (7.4 GB)
-REST=1 userland/build.sh # the APFS images: userland/root.apfs and userland/system.apfs
-make loader # the boot loader, with the iPhone's identity taken from YOUR copy of the IPSW (needs clang and lld)
-mkdir -p logs
-qemu/run-ios.sh 1200 -display gtk > logs/qemu.log # a 20-minute session
+make doctor # what this machine lacks, and what to do
+make qemu-open # the open kernel in QEMU: nothing of Apple's, nothing of a phone's
```
-**What you will see.** The CPU is emulated, so it is slow, and the window is **black at first**: that is normal.
-Black for the first minute, then the Apple logo, then the home screen after about 5 minutes on a fast desktop (measured on
-one: the logo at 1 minute, the home screen at 5), longer on a slower machine. The mouse with the button held is a finger; `H` is Home, `L` is the power button, `↑`/`↓` are volume.
-
-**If it stays black** (check these in order):
-
-0. Did you run `make loader`? `prebuilt/loader.efi` has no Apple data in it on purpose (it boots the open kernel only), and with it
- iOS does not start: `qemu/run-ios.sh` now refuses to run without your own `xnuloader/loader.efi` and says so.
-1. `tail -f logs/qemu.log` in another terminal. It should print `== XNULOADER v3 ==` within seconds and kernel and launchd
- lines after that. If it prints nothing, QEMU did not start the loader: run `make doctor`.
- A log that runs, with the line `ramfb: control ... after the request` near its top, is a loader built before 27 October 2026
- (a compiler could skip the check of the display request): the window stays at 800x600 and iOS draws outside it. `make loader`
- again.
-2. `qemu/screendump.sh` saves what the guest's screen shows (`logs/qemu-screen.png`), whatever your window does.
-3. No window or a black one although the log runs: your QEMU may have no GTK window (a headless package, WSL without WSLg).
- Use `qemu/run-ios.sh 1200 -display vnc=127.0.0.1:0 > logs/qemu.log` and connect a VNC viewer to `127.0.0.1:5900`.
-4. The guest asks QEMU for 7 GB of memory (`QEMU_RAM_GB`; 6 at the very least, the system image sits 3 GB into it and is 2.5 GB). On a machine without that, the host swaps and
- everything is very slow; close other programs or give the VM or WSL more memory.
-5. `qemu/run-ios.sh` needs the images from the two steps above (`userland/system.apfs` and `userland/root.apfs`): a
- missing one is reported at once, not as a black window.
-
-## On the phone
-
-A phone with a port (`devices/redwood/`, POCO X5 Pro 5G), its boot loader unlocked, `adb` and
-`fastboot` on the PC, the images from the previous section, and the phone's own firmware:
+iOS in QEMU (Linux, 12 GB of disk, Apple's IPSW downloaded for you), and a session on the phone:
+[QEMU](docs/getting-started/qemu.md), [On the phone](docs/getting-started/phone.md).
```sh
-devices/redwood/pull-firmware.sh # GPU, Wi-Fi, audio/battery, haptics, modem, cameras -> fw-*/
-make loader # (once, the quick start's step) the loader with the identity from your own IPSW
-./xl enter # Android -> fastboot -> our loader in RAM
-./xl ramdisk userland/system.apfs # the system image into the phone's RAM (~80 s), once per loader session
-XL_SB_DELAY=8 XL_SECS=600 \
-XL_CMDLINE="bootcpu=7 cpus=8 cpufreq=1 ufs=2 touchscreen=1 gpu=1 adsp=1 sound=4 wifi=1 haptic=5 modem=1" \
-./xl run # a 10-minute session, the log goes to logs/
-./xl reboot # back to Android
+make redwood_defconfig # the phone's configuration: the common kernel + the SC7280's + the phone's own
+make kernel # the kernel with the drivers that configuration builds
+make phone SECS=600 # a 10-minute session on the phone, in RAM
```
-`tools/modem-cycle.sh "ARGS" SECS` does all of that in one command and returns the phone to Android.
-
-The main kernel arguments (the full list is in `docs/ru/notes.md`):
+## Repositories: common, SoC, device
-| Argument | What it does |
+| Where | What |
|---|---|
-| `cpus=8 bootcpu=7 cpufreq=1` | all CPU cores and their clocks |
-| `touchscreen=1` | the touch screen |
-| `gpu=1` | rendering on Adreno (an image built with `GL=1`, firmware in `fw-gpu/`) |
-| `adsp=1 sound=4 mic=4` | the audio DSP: speakers, microphone; battery and charging come with it |
-| `haptic=5` | the vibration motor |
-| `wifi=1` | Wi-Fi (the network from `fw-wifi/network`) |
-| `cam=5` | the cameras |
-| `modem=1` | the modem beside the system: its firmware, file systems, IPA, SIM, NAS |
-| `modem_step=N` | the modem step by step, for debugging (`docs/cellular.md`) |
-| `var_store=1 ufs_write=1` | keep `/private/var` across reboots |
-
-## Building from source
-
-The kernel (Linux: theos with its cctools and `iPhoneOS16.5.sdk`; macOS: Xcode or cctools, the SDK
-is fetched for you):
+| this repository | **common**: the kernel port (`xnu/`), every common driver (`drivers/`), the loader (`xnuloader/`), user space (`userland/`), the tools, the documentation |
+| `socs/sc7280/` | the Qualcomm SC7280 family (Snapdragon 778G): its fragment, its drivers' choice |
+| `devices/redwood/` | POCO X5 Pro 5G: its defconfig, status, UEFI port, firmware script |
+| `devices/qemu/` | QEMU's `virt` machine, as a device: none of a phone's drivers built in |
+| `devices/manifest.conf` | every SoC and device repository, in this tree or a repository of its own at a revision |
-```sh
-xnu/apply.sh # XNU sources from Apple's GitHub + my changes -> xnu-src/
-xnu-deps/setup.sh # dependencies, tools and the SDK
-./xnu-build.sh -j8 -k # -> xnu-src/.../BUILD/obj/DEVELOPMENT_ARM64_BCM2837/mach.development.bcm2837
-```
+A device is a repository of its own over the common one: `tools/hakios-device.py new` makes it from the phone's own device tree,
+with every phone driver left out until it is ported; `split` makes it a git repository; `sync` fetches the ones that live
+elsewhere. 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](docs/porting/repositories.md),
+[Drivers in the configuration](docs/drivers-config.md).
-The loader: `xnuloader/build.sh` (clang + lld-link, an EFI application without EDK2). The header
-`xnuloader/identity.h`, the properties by which iOS tells which iPhone it is, is not kept in the
-repository: `xnuloader/mkidentity.sh` makes it at build time from the device tree in your own IPSW
-(one 34 KB file; LZFSE is decoded by `lzfse`, macOS's `compression_tool` or the Python `lzfse`
-module, or the open lzfse library gets built). User space and the images: `REST=1 userland/build.sh`
-(`MODEM=1 SYSTEM=1` put the modem's firmware into the system image). Details: `xnu/README.md`,
-`docs/ru/notes.md`.
+## What is in the repository, and what never is
-## Layout
+In it: only our own code and data: the patch to Apple's open-source XNU (`xnu/hakios.patch`, 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 iOS, on your machine, from your own IPSW), and the device and SoC directories.
-| Directory | Contents |
-|---|---|
-| `xnu/` | the kernel patch and files; `apply.sh`, `export.sh`; a README about the kernel |
-| `drivers/*/hakios.*` | my drivers: display, touch, UFS, GPU, Wi-Fi, audio, modem (`hakios.mpss.c`), its packets (`hakios.ipa.c`, `hakios.cell.c`), SIM/NAS, haptics, cameras |
-| `xnuloader/` | the boot loader (a UEFI application) |
-| `userland/` | my programs and libraries (`src/`), the image build, launchd jobs |
-| `sysimage/` | scripts that fetch and unpack the OS files from the IPSW (none of the files themselves) |
-| `devices/redwood/` | one phone: its UEFI port, device tree, prebuilt UEFI images, firmware script, tools |
-| `tools/` | APFS, firmware, QMI tests, run scripts |
-| `qemu/` | running in QEMU |
-| `docs/` | `notes.md`: the detailed notes (Russian); `cellular.md`: cellular; `air.md`, `metal.md`: the GPU |
-| `prebuilt/` | the built kernel, loader and libraries |
-
-## Devices
-
-The kernel, loader and user space are shared. Everything about one phone lives in
-`devices/<name>/`: its UEFI, device tree, firmware list and tools. Today there is one,
-`devices/redwood/`, and its README is the map of what a port to another Qualcomm phone must bring.
-The phone's drivers are the files `drivers/*/hakios.*` (by subsystem: `drivers/README.md`); the head of each says where its
-numbers came from.
-
-## Cellular
-
-The modem (the Hexagon MPSS) is brought up from XNU: firmware through TrustZone, shared memory,
-SMP2P, GLINK, QRTR, QMI; its file systems are served from the UFS (read-only, writes stay in kernel
-memory), TFTP and the service registry are mine. The IPA packet engine runs with its firmware,
-clock and SMMU context, and the handshake with the modem goes through. The SIM is bound to the
-subscription and NAS reads the signal. The current state and the whole story are in
-`docs/cellular.md`.
+Never in it: any file of iOS (you build the system image on your machine from the IPSW, which `sysimage/fetch.sh` downloads from
+Apple's public servers without decrypting or circumventing anything); 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.
## Independent, and Apple-free at the core
@@ -218,7 +112,7 @@ these statements), `COMPLIANCE.md` (how the APSL 2.0 and other terms are met, an
to verify), `THIRD_PARTY_LICENSES.md` (every third-party component with origin and license), and
`NOTICE` (the short canonical list). None of this is legal advice.
-hakios is an experimental project focused on bringing ios to android hardware. our goal is to make hackios free and accessible to everyone.
+hakios is an experimental project focused on bringing ios to android hardware. our goal is to make hakios free and accessible to everyone.
owners:
@oodze - founder
diff --git a/README.uk.md b/README.uk.md
index 4c8d189..b624192 100644
--- a/README.uk.md
+++ b/README.uk.md
@@ -2,6 +2,8 @@
[English](README.md) · [中文](README.zh.md) · Українська
+> **Зверніть увагу:** цей переклад відповідає попередній версії англійського README. Актуальні: [README.md](README.md) і документація в [docs/](docs/index.md): репозиторії пристроїв (`devices/<name>`, `socs/<soc>`), драйвери в конфігурації (`CONFIG_HAKIOS_*`), Metal.
+
HakiOS — це адаптація ядра Darwin (відкритий XNU від Apple, xnu-8796.121.2) до Android-телефонів із Qualcomm, так
само як Android — адаптація Linux до телефонів: власний завантажувач, власні драйвери, система конфігурацій
(`configs/`) і власна версія ядра (`VERSION`). Те саме працює в QEMU (`virt`, aarch64) на комп'ютері з Linux, без
@@ -74,7 +76,7 @@ HakiOS — це адаптація ядра Darwin (відкритий XNU ві
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
+git clone https://github.com/shimoku74/hakios.git hakios
cd hakios
make doctor # чого бракує цьому комп'ютеру (дисплей QEMU, UEFI, пам'ять) і що робити
make fetch # IPSW iOS 16.5 із серверів Apple, потрібне розпаковується (7,4 ГБ)
diff --git a/README.zh.md b/README.zh.md
index 6674f2e..6f6dbd0 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -2,6 +2,8 @@
[English](README.md) · 中文 · [Українська](README.uk.md)
+> **注意:** 本译文对应英文 README 的旧版本。最新内容见 [README.md](README.md) 和 [docs/](docs/index.md) 中的文档:设备仓库(`devices/<name>`、`socs/<soc>`)、配置中的驱动(`CONFIG_HAKIOS_*`)以及 Metal。
+
HakiOS 是把 Darwin 内核(Apple 开源的 XNU,xnu-8796.121.2)适配到搭载高通 SoC 的 Android 手机上,就像 Android 是
Linux 在手机上的适配:我自己的引导程序、驱动、配置系统(`configs/`)和独立的内核版本号(`VERSION`)。同样的东西也能在
Linux 电脑上的 QEMU(`virt`,aarch64)里运行,不需要任何 Apple 的东西,也不需要任何手机的东西(`make qemu-open`)。
@@ -66,7 +68,7 @@ Linux 电脑上的 QEMU(`virt`,aarch64)里运行,不需要任何 Apple
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
+git clone https://github.com/shimoku74/hakios.git hakios
cd hakios
make doctor # 检查本机缺什么(QEMU 显示设备、UEFI 固件、内存)以及怎么办
make fetch # 从 Apple 服务器取 iOS 16.5 IPSW,解包所需部分(7.4 GB)
diff --git a/ci/github-check.yml b/ci/github-check.yml
index 010c63f..e0ec4d6 100644
--- a/ci/github-check.yml
+++ b/ci/github-check.yml
@@ -44,8 +44,18 @@ jobs:
run: |
python3 tools/boot-args-test.py
python3 tools/boot-args.py --check
- - name: The drivers are kept by subsystem and every one is in drivers/map
+ - name: The drivers are kept by subsystem, every one is in drivers/map, and drivers/*/conf builds each exactly once
run: python3 tools/drivers-check.py
+ - name: The device and SoC repositories hold together, and a device's own drivers reach the kernel
+ run: |
+ python3 tools/hakios-device.py check
+ python3 tools/hakios-device-test.py
+ - name: The documentation pages made from the source are current
+ run: |
+ python3 tools/docs-gen.py --check
+ python3 tools/docs-check.py
+ - name: The Metal plug-in's reading of a .metallib refuses every file cut short or bent (sanitizers)
+ run: sh tools/metallib-test.sh
- name: The kernel patch applies to Apple's tree
run: |
git clone -q --depth 1 --branch xnu-8796.121.2 https://github.com/apple-oss-distributions/xnu.git /tmp/xnu
diff --git a/configs/boot-args.lst b/configs/boot-args.lst
index 7407d6d..bc8e9c6 100644
--- a/configs/boot-args.lst
+++ b/configs/boot-args.lst
@@ -58,6 +58,8 @@ battery_stop k
battery_stop_poll k
battmgr k
bootcpu kl
+bt k
+bt_again k
buttons k
buttons_steps k
ca_vbl u
@@ -142,6 +144,7 @@ hv_wdt_pet k
loader_return_after kl
machine_name k
membench k
+metal ku
mic k
mic_adc k
mic_input k
diff --git a/configs/common_defconfig b/configs/common_defconfig
index 5424115..3d8b427 100644
--- a/configs/common_defconfig
+++ b/configs/common_defconfig
@@ -1,8 +1,8 @@
#
# HakiOS common defconfig: every setting there is, with what it does.
-# Made by tools/hakios-config.py listing common; the values are the ones that file sets, and tests/CI check that it names every symbol.
+# Made by tools/hakios-config.py listing common -o <this file>; the values are the ones that file sets, and tests/CI check that it names every symbol.
#
-# 313 symbols in 17 groups; 2 are set.
+# 341 symbols in 18 groups; 34 are set, 25 of them drivers built in.
#
#
@@ -16,14 +16,93 @@
# CONFIG_SOC is not set
# "device": options may use firmware pulled from your own phone (fw-*/); "none": the open configuration, nothing of ...
-CONFIG_FIRMWARE="none"
+CONFIG_FIRMWARE="device"
+
+#
+# Drivers built in (25)
+#
+
+# the audio DSP started and linked (adsp=1, adsp_step=N); the battery's state comes through it too. Needs the DSP's ... [hakios.adsp.c]
+CONFIG_HAKIOS_ADSP=y
+
+# the two speaker amplifiers on I2C, and their watch of temperature and battery [hakios.speaker.c]
+CONFIG_HAKIOS_SPEAKER=y
+
+# the speakers playing (sound=N): what the DSP's services are told, the feeder, and the speakers' guard that limits ... [hakios.sound.c, hakios.guard.c; requires CONFIG_HAKIOS_ADSP, CONFIG_HAKIOS_SPEAKER]
+CONFIG_HAKIOS_SOUND=y
+
+# the microphones, through the audio DSP (mic=N) [hakios.mic.c; requires CONFIG_HAKIOS_ADSP, CONFIG_HAKIOS_SOUND]
+CONFIG_HAKIOS_MIC=y
+
+# QEMU's virtio sound device as the player of /dev/hakios-audio (virtio_sound=1). QEMU only [hakios.virtio_sound.c]
+CONFIG_HAKIOS_VIRTIO_SOUND=y
+
+# the Bluetooth half of the WCN6750: step one, a read-only look at its three pins (bt=1) [hakios.bt.c]
+CONFIG_HAKIOS_BT=y
+
+# the cameras (cam=N): the sensors on the CCI bus and the ISP's interface. The sensors, their tables (fw-camera/) and ... [hakios.camera.c]
+CONFIG_HAKIOS_CAMERA=y
+
+# the flashlight: the flash LED module of the PM8350C (torch=1); it stays off while the battery is too warm [hakios.torch.c]
+CONFIG_HAKIOS_TORCH=y
+
+# the chip's identity from the firmware's shared memory: kern.hakios.soc_* (socinfo=1). Any Qualcomm SoC that keeps ... [hakios.socinfo.c]
+CONFIG_HAKIOS_SOCINFO=y
+
+# the Adreno 642L of the SC7280 woken step by step (adreno=N), and HakiosGPU, the IOKit service Mesa and the window ... [hakios.adreno.c, hakios.gpu.cpp]
+CONFIG_HAKIOS_ADRENO=y
+
+# the vibration motor: an Awinic AW86927 driving a linear resonant actuator (haptic=N), its waveforms from fw-haptic/ [hakios.haptic.c]
+CONFIG_HAKIOS_HAPTIC=y
+
+# QEMU's virtio tablet and keyboard as the touch screen and the buttons (virtio_input=1). QEMU only [hakios.virtio_input.c]
+CONFIG_HAKIOS_VIRTIO_INPUT=y
+
+# the touch screen: a Goodix GT9916 ("Berlin-D") or a FocalTech FT3680 on SPI (touchscreen=1). The bus, pins and ... [hakios.goodix.c]
+CONFIG_HAKIOS_GOODIX=y
+
+# the power and volume keys, read from the PMIC through the SPMI arbiter (buttons=1) [hakios.buttons.c]
+CONFIG_HAKIOS_BUTTONS=y
+
+# QMI messages over the IPC router: how the Wi-Fi firmware's service and the modem's are spoken to [hakios.qmi.c]
+CONFIG_HAKIOS_QMI=y
+
+# the modem (modem=1): started, its file systems served from the flash, the IPA's data path as en1, the SIM and the ... [hakios.mpss.c, hakios.cell.c, hakios.nas.c, hakios.ipa.c; requires CONFIG_HAKIOS_QMI, CONFIG_HAKIOS_UFS]
+CONFIG_HAKIOS_MODEM=y
+
+# QEMU's virtio network device as the link behind en0 (virtio_net=1). QEMU only [hakios.virtio_net.c]
+CONFIG_HAKIOS_VIRTIO_NET=y
+
+# the battery: kern.hakios.battery_*, and HakiosBattery, the IOPMPowerSource iOS reads the charge from (the state ... [hakios.battery.c, hakios.battery.cpp]
+CONFIG_HAKIOS_BATTERY=y
+
+# the clock of the cores the kernel runs on (cpufreq=1), and the memory bus's votes (ddr=) [hakios.cpufreq.c]
+CONFIG_HAKIOS_CPUFREQ=y
+
+# the SoC's temperature sensors (thermal=1): kern.hakios.thermal_*, and the run handed back to the loader when the ... [hakios.thermal.c]
+CONFIG_HAKIOS_THERMAL=y
+
+# the blocks of the power-management chips the SPMI arbiter shows, and the PMIC's clock (pmic=1); read only [hakios.pmic.c]
+CONFIG_HAKIOS_PMIC=y
+
+# the run handed back to the loader before the battery is flat (battery_stop=<percent>) [hakios.battguard.c]
+CONFIG_HAKIOS_BATTGUARD=y
+
+# the phone's UFS flash: a block device for each GPT partition (ufs=1, ufs=2), and the UFS host controller driven from ... [hakios.ufs.c, hakios.ufshc.c]
+CONFIG_HAKIOS_UFS=y
+
+# a disk image of the host as /dev/rvblk0 (virtio_blk=1). QEMU only [hakios.virtio_blk.c]
+CONFIG_HAKIOS_VIRTIO_BLK=y
+
+# Wi-Fi of the WCN6750 (wifi=1, wifi_step=N): the DSP that runs the radio's firmware, Linux's ath11k (its object, made ... [hakios.wifi.c, hakios.wlfw.c, hakios.lx.c, hakios.sta.c, hakios.apple80211.c, hakios.wlan.cpp; requires CONFIG_HAKIOS_QMI]
+CONFIG_HAKIOS_WIFI=y
#
# CPU, memory and boot (21)
#
# CPU cores the kernel uses, 1 to 8; one if not set
-CONFIG_CPUS=1
+# CONFIG_CPUS is not set
# the core the kernel runs on, 0 to 7; 7 is the biggest core (the loader keeps core 0)
# CONFIG_BOOTCPU is not set
@@ -90,7 +169,7 @@ CONFIG_CPUS=1
#
# the phone's storage: 1 a survey, read only; 2 the loader's block service, through which the kernel reads it (the ...
-# CONFIG_UFS is not set
+CONFIG_UFS=2
# let the kernel write, to the partition `darwin` and nowhere else (writes to the phone's storage: it is the one ... [requires CONFIG_UFS=2]
# CONFIG_UFS_WRITE is not set
@@ -226,7 +305,7 @@ CONFIG_CPUS=1
#
# the touch screen, and the power and volume buttons
-# CONFIG_TOUCHSCREEN is not set
+CONFIG_TOUCHSCREEN=y
# read by hakios.buttons.c (kernel)
# CONFIG_BUTTONS is not set
@@ -250,11 +329,11 @@ CONFIG_CPUS=1
# CONFIG_VIRTIO_INPUT is not set
#
-# GPU and display (67)
+# GPU and display (68)
#
# rendering on Adreno (an image built with GL=1; the GPU's firmware from your phone) [needs fw-gpu/ from the phone]
-# CONFIG_GPU is not set
+CONFIG_GPU=y
# read by hakios.adreno.c (kernel)
# CONFIG_ADRENO is not set
@@ -424,6 +503,9 @@ CONFIG_CPUS=1
# read by hakios.adreno.c (kernel)
# CONFIG_GPU_LOG is not set
+# only the program metal_test (userland/src/metal_test.m): the safe level, for seeing what Metal does with the device
+# CONFIG_METAL is not set
+
# read by MiniIOMobileFramebuffer.cpp (kernel)
# CONFIG_REC_MB is not set
@@ -459,10 +541,10 @@ CONFIG_CPUS=1
#
# the audio DSP; the battery level in the UI and charging state come through it [needs fw-audio/ from the phone]
-# CONFIG_ADSP is not set
+CONFIG_ADSP=y
# the speakers (4 is what the README's phone line uses) [needs fw-audio/ from the phone] [requires CONFIG_ADSP]
-# CONFIG_SOUND is not set
+CONFIG_SOUND=4
# the microphone (4 is what the README's phone line uses) [needs fw-audio/ from the phone] [requires CONFIG_ADSP]
# CONFIG_MIC is not set
@@ -559,7 +641,7 @@ CONFIG_CPUS=1
#
# Wi-Fi: the radio, its driver, a connection (also fw-wifi/mac and fw-wifi/network) [needs fw-wifi/ from the phone]
-# CONFIG_WIFI is not set
+CONFIG_WIFI=y
# start the DSP although the one before it was shut down without having acknowledged a stop: THAT HAS RESET THE PHONE, ...
# CONFIG_WIFI_AGAIN is not set
@@ -656,10 +738,10 @@ CONFIG_CPUS=1
#
# the modem beside the system: its firmware, file systems, IPA, SIM, NAS [needs fw-modem/ from the phone] [requires CONFIG_UFS=2]
-# CONFIG_MODEM is not set
+CONFIG_MODEM=y
# start the modem although a kernel before this one left it shut down [requires CONFIG_MODEM]
-# CONFIG_MODEM_AGAIN is not set
+CONFIG_MODEM_AGAIN=y
# the modem's RMTFS buffer, an address below 4 GB (0xa8000000 on the reference phone) [requires CONFIG_MODEM]
# CONFIG_MODEM_BUFFER is not set
@@ -969,12 +1051,18 @@ CONFIG_CPUS=1
# CONFIG_UFS_PROBE is not set
#
-# User space (11)
+# User space (13)
#
# read by inject_sb.c (user space)
# CONFIG_AUTOUNLOCK is not set
+# read by hakios.bt.c (kernel)
+# CONFIG_BT is not set
+
+# the second look this many seconds later (0: no second look; 30)
+# CONFIG_BT_AGAIN is not set
+
# CoreAnimation's frame clock from the display driver's refresh notifications
# CONFIG_CA_VBL is not set
diff --git a/configs/symbols.tsv b/configs/symbols.tsv
index bfbeb5d..6a3244b 100644
--- a/configs/symbols.tsv
+++ b/configs/symbols.tsv
@@ -53,6 +53,8 @@ APPLOG_NAME arg applog_name CPU, memory and boot k (patch)
AUTOUNLOCK arg autounlock User space u inject_sb.c
BATTERY arg battery Audio and battery kl hakios.adsp.c,hakios.battery.c,loader.c
BATTMGR arg battmgr Audio and battery k hakios.adsp.c every property once, for the log (which number is which on this phone's firmware)
+BT arg bt User space k hakios.bt.c
+BT_AGAIN arg bt_again User space k hakios.bt.c the second look this many seconds later (0: no second look; 30)
BUTTONS arg buttons Touch and buttons k hakios.buttons.c
BUTTONS_STEPS arg buttons_steps Touch and buttons k hakios.buttons.c
CA_VBL arg ca_vbl User space u inject.c CoreAnimation's frame clock from the display driver's refresh notifications
@@ -128,6 +130,7 @@ GPU_LOG arg gpu_log GPU and display k hakios.adreno.c
HAPTIC_EFFECT arg haptic_effect Haptics and torch k hakios.haptic.c
MACHINE_NAME arg machine_name CPU, memory and boot k GenericARMPE.cpp
MEMBENCH arg membench CPU, memory and boot k hakios.cpufreq.c
+METAL arg metal GPU and display ku HakiosMetal.m,MiniIOMobileFramebuffer.cpp only the program metal_test (userland/src/metal_test.m): the safe level, for seeing what Metal does with the device
MIC_ADC arg mic_adc Audio and battery k hakios.mic.c
MIC_INPUT arg mic_input Audio and battery k hakios.mic.c
MIC_MAIN arg mic_main Audio and battery k hakios.mic.c
diff --git a/devices/manifest.conf b/devices/manifest.conf
new file mode 100644
index 0000000..a89d97b
--- /dev/null
+++ b/devices/manifest.conf
@@ -0,0 +1,18 @@
+# devices/manifest.conf: every SoC and device repository HakiOS knows of (Android's repo manifest, UniXNU's devices.toml).
+#
+# soc|device <name>
+# path <directory in this tree> kept here, for now: tools/hakios-device.py split makes it a repository
+# repository <git URL> a repository of its own, cloned into socs/<name> or devices/<name>
+# revision <commit> ... at this commit (tools/hakios-device.py lock writes it)
+#
+# `tools/hakios-device.py sync` clones and updates the ones with a repository; `list` shows them all; docs/porting/repositories.md
+# is the guide. A device of yours: open a pull request that adds its block here, with its repository and revision.
+
+soc sc7280
+ path socs/sc7280
+
+device redwood
+ path devices/redwood
+
+device qemu
+ path devices/qemu
diff --git a/devices/qemu/configs/qemu_defconfig b/devices/qemu/configs/qemu_defconfig
new file mode 100644
index 0000000..653d46c
--- /dev/null
+++ b/devices/qemu/configs/qemu_defconfig
@@ -0,0 +1,30 @@
+# HakiOS defconfig for QEMU's virt machine: the common kernel with the drivers of a virtual machine built in and none of a phone's.
+# What a device's defconfig looks like when it chooses its drivers (docs/drivers-config.md): the phone's drivers are left out of
+# the kernel, not only switched off at boot, and the arguments that only they read go with them (the check refuses them otherwise).
+#include common_defconfig
+#include open.config
+#include virt.config
+CONFIG_DEVICE="qemu"
+# CONFIG_UFS is not set
+# CONFIG_TOUCHSCREEN is not set
+# CONFIG_HAKIOS_GOODIX is not set
+# CONFIG_HAKIOS_BUTTONS is not set
+# CONFIG_HAKIOS_UFS is not set
+# CONFIG_HAKIOS_ADRENO is not set
+# CONFIG_HAKIOS_CAMERA is not set
+# CONFIG_HAKIOS_TORCH is not set
+# CONFIG_HAKIOS_HAPTIC is not set
+# CONFIG_HAKIOS_ADSP is not set
+# CONFIG_HAKIOS_SPEAKER is not set
+# CONFIG_HAKIOS_SOUND is not set
+# CONFIG_HAKIOS_MIC is not set
+# CONFIG_HAKIOS_BATTERY is not set
+# CONFIG_HAKIOS_CPUFREQ is not set
+# CONFIG_HAKIOS_THERMAL is not set
+# CONFIG_HAKIOS_PMIC is not set
+# CONFIG_HAKIOS_BATTGUARD is not set
+# CONFIG_HAKIOS_SOCINFO is not set
+# CONFIG_HAKIOS_WIFI is not set
+# CONFIG_HAKIOS_BT is not set
+# CONFIG_HAKIOS_QMI is not set
+# CONFIG_HAKIOS_MODEM is not set
diff --git a/devices/qemu/device.conf b/devices/qemu/device.conf
new file mode 100644
index 0000000..4cd83e5
--- /dev/null
+++ b/devices/qemu/device.conf
@@ -0,0 +1,15 @@
+# devices/qemu/device.conf: QEMU's virt machine as a device: what a port looks like with none of a phone's drivers built in.
+
+device qemu
+ title QEMU virt (aarch64)
+ vendor QEMU
+ soc none
+ defconfig qemu_defconfig
+ maintainer the HakiOS developers (README.md)
+ status display works ramfb, through the loader
+ status touch works virtio tablet as the touch screen (CONFIG_HAKIOS_VIRTIO_INPUT)
+ status buttons works virtio keyboard: H is Home, L the power button, arrows the volume
+ status storage works virtio-blk images (CONFIG_HAKIOS_VIRTIO_BLK)
+ status audio works virtio sound (CONFIG_HAKIOS_VIRTIO_SOUND)
+ status network works virtio-net as en0 (CONFIG_HAKIOS_VIRTIO_NET)
+ status gpu missing no GPU: the screen is drawn in software
diff --git a/devices/redwood/configs/redwood_defconfig b/devices/redwood/configs/redwood_defconfig
index 4883307..170541a 100644
--- a/devices/redwood/configs/redwood_defconfig
+++ b/devices/redwood/configs/redwood_defconfig
@@ -1,6 +1,6 @@
# HakiOS defconfig for the POCO X5 Pro 5G (redwood, SM7325, devices/redwood): the common kernel's configuration, the SC7280 family's
# facts and this phone's own, put together the way Android puts a device's kernel configuration together.
-# What the project's own phone line uses, with the sensors read (and the run stopped at 105 degrees) as the only addition.
+# What the project's own phone line uses, with the chip's identity and the sensors read as the only additions (stopping a hot run, CONFIG_THERMAL_STOP, is not set).
# Needs the phone's own firmware pulled from your phone (devices/redwood/pull-firmware.sh): `tools/hakios-config.py needs`.
#include common_defconfig
#include sc7280.config
diff --git a/devices/redwood/device.conf b/devices/redwood/device.conf
new file mode 100644
index 0000000..84fa517
--- /dev/null
+++ b/devices/redwood/device.conf
@@ -0,0 +1,25 @@
+# devices/redwood/device.conf: what this device repository is. tools/hakios-device.py reads it; docs/porting/repositories.md has
+# every word, and the device's page (docs/devices/redwood.md) is made from it, so that the status is said in one place.
+
+device redwood
+ title POCO X5 Pro 5G
+ vendor Xiaomi
+ soc sc7280
+ defconfig redwood_defconfig
+ firmware pull-firmware.sh
+ maintainer the HakiOS developers (README.md)
+ status display works the panel through UEFI's framebuffer; frames drawn by the GPU with gpu=1
+ status touch works Goodix GT9916 / FocalTech FT3680 on SPI, multitouch (CONFIG_HAKIOS_GOODIX, touchscreen=1)
+ status buttons works power and volume through the PMIC (CONFIG_HAKIOS_BUTTONS)
+ status cpu works all 8 cores, the big core at 2.4 GHz (cpus=8 bootcpu=7 cpufreq=1)
+ status gpu works Adreno 642L, OpenGL ES through Mesa (gpu=1); Metal: buffers and libraries, no drawing yet
+ status storage works UFS read through the loader; /private/var kept with var_store=1 ufs_write=1
+ status audio works speakers and microphone through the audio DSP (adsp=1 sound=4 mic=4)
+ status battery partial the level in the UI through the audio DSP; charging under this kernel is not done
+ status haptic works Awinic AW86927 (haptic=5)
+ status camera works Camera.app (cam=5)
+ status torch partial the PM8350C flash LED and Control Center's button (torch=N); not in the README's list of what works
+ status wifi works WCN6750 with Linux's ath11k: radio, driver, a network joined (wifi=1)
+ status bluetooth missing step one only: a read-only look at its pins (bt=1)
+ status cellular partial the modem boots, sees the network, the SIM is bound, IPA and en1 in place; no registration yet
+ status thermal partial 27 of 27 sensors read on the phone (thermal=1); the stop (thermal_stop=) not yet seen firing
diff --git a/devices/redwood/uefi/README.md b/devices/redwood/uefi/README.md
index 0ba1e2d..8e69a39 100644
--- a/devices/redwood/uefi/README.md
+++ b/devices/redwood/uefi/README.md
@@ -1,71 +1,17 @@
# UEFI for redwood
-A port of [Project Silicium / Mu-Silicium](https://github.com/Project-Silicium/Mu-Silicium) to the
-POCO X5 Pro 5G, modelled on `lisa` (the same `KodiakPkg` SoC package).
-The image is built on your machine, from your own phone's firmware: the vendor's drivers that go into
-it are not in this repository (see below).
+The POCO X5 Pro 5G's platform for HakiOS's UEFI (`uefi/` of the common repository: Mu-Silicium with HakiOS's changes and banner).
+It is modelled on `lisa` (the same `KodiakPkg` SoC package).
-What is here:
+What is here, in `files/`:
-- `BASE`: the Mu-Silicium commit the port is made on;
-- `mu-silicium.patch`: changes to existing files: `BootShim/BootShim.S` (copies our "XNUP"
- container behind the UEFI image to 0xF0000000) and `BootManagerLib` (starts the XNU loader from
- the container instead of a menu);
-- `files/`: new files: `Platforms/Xiaomi/redwoodPkg` (memory map, driver list),
- `Silicon/.../BootManagerLib/XnuLoader.[ch]`, `Resources/Configs/redwood.toml`,
- `Resources/DTBs/redwood.dtb` (the device tree from the phone's vendor_boot), `Binaries/redwood`
- (the vendor's UEFI drivers: **not tracked**, you make this directory yourself, see below;
- `files/Binaries/redwood/README.md` is kept: it lists the patches that were applied to them).
-
-## The vendor's drivers are not in the repository
-
-A phone's UEFI is made of open code (Project Mu, EDK2) and of drivers that Qualcomm and Xiaomi wrote for
-that phone: display, storage, USB, secure boot and more. They are proprietary and have not been
-licensed for redistribution, so this repository carries neither them (`files/Binaries/redwood/*`) nor
-the UEFI image built with them (`prebuilt/SILICIUM_UEFI.fd`). `tools/provenance-check.py` fails the
-build if they come back; it runs on every push, and `tools/provenance.allow` says why each binary that
-*is* here may be.
-
-Without that image `mkxnuimg.py` stops with a message that points here. To get one, make both from
-**your own phone**:
-
-1. Get your phone's UEFI firmware: the vendor's `xbl` firmware, which is on the phone (with root, the
- `xbl` partition) and in the vendor's firmware package for your model and region.
- `files/Binaries/redwood/README.md` records the version the port was made on (`OS1.0.3.0.UMSMIXM`):
- another version may need other patches.
-2. Extract the drivers from it with [UEFIReader](https://github.com/WOA-Project/UEFIReader) into
- `files/Binaries/redwood/`. Its README says no more than what the tool is for ("generate .inf
- payloads ... out of an existing UEFI volume", as of 2026-10-26); Mu-Silicium's documentation for a
- device describes the layout it expects. **The authors of this repository have not repeated this
- extraction since the drivers were taken out of the tree: if you do it, say what worked in an
- issue.**
-3. Build as below. `mkxnuimg.py` then takes the image from `Mu-Silicium/`.
-
-What you extract is the vendor's, from your own device: keep it on your disk and never commit it.
-
-## Build
-
-Packages as in Mu-Silicium's `setup_env.sh` (Arch: `git base-devel lld nasm clang llvm
-aarch64-linux-gnu-gcc python python-pip python-virtualenv`).
-
-```sh
-devices/redwood/uefi/apply.sh # clones Mu-Silicium (with submodules, ~3 GB) and applies the port
-python3 -m venv venv && venv/bin/pip install -r Mu-Silicium/pip-requirements.txt
-cd Mu-Silicium
-source ../venv/bin/activate
-python3 build_uefi.py -d redwood -r RELEASE # -> Build/redwoodPkg/RELEASE_CLANGPDB/FV/SILICIUM_UEFI.fd
-```
-
-The `mu_nasm` dependency comes through NuGet and wants Mono; without Mono, point it at the
-system nasm:
+- `Platforms/Xiaomi/redwoodPkg`: the memory map and the driver list;
+- `Resources/Configs/redwood.toml`, `Resources/DTBs/redwood.dtb` (the device tree from the phone's vendor_boot);
+- `Binaries/redwood`: the vendor's UEFI drivers, **not tracked**: you make this directory yourself from your own phone
+ (`uefi/README.md` says how); `files/Binaries/redwood/README.md` is kept: it lists the patches that were applied to them.
```sh
-D=Mu_Basecore/BaseTools/Bin/mu_nasm_extdep
-mkdir -p $D/Linux-x86-64
-echo 'version: 20016.1.1' > $D/extdep_state.yaml
-ln -s /usr/bin/nasm /usr/bin/ndisasm $D/Linux-x86-64/
+devices/redwood/uefi/apply.sh # = uefi/apply.sh redwood
```
-After a build, `mkxnuimg.py` (called by `./xl enter`) takes the UEFI from `Mu-Silicium/`, and
-`tools/update-prebuilt.sh` refreshes `devices/redwood/prebuilt`. `devices/redwood/uefi/export.sh`
-is the reverse: it saves the changes from `Mu-Silicium/` here.
+The build and the vendor's drivers: [uefi/README.md](../../../uefi/README.md).
diff --git a/devices/redwood/uefi/apply.sh b/devices/redwood/uefi/apply.sh
index 99e00b5..f3b3926 100755
--- a/devices/redwood/uefi/apply.sh
+++ b/devices/redwood/uefi/apply.sh
@@ -1,13 +1,4 @@
#!/bin/bash
-# Make ../Mu-Silicium: a clone of Project-Silicium/Mu-Silicium at the commit our port was made on,
-# with the redwood port (this directory) put into it. See README.md here for how to build it.
-set -e
-cd "$(dirname "$(readlink -f "$0")")"
-MU=../../../Mu-Silicium
-[ -e $MU ] && { echo "uefi/apply.sh: $MU already exists"; exit 1; }
-git clone https://github.com/Project-Silicium/Mu-Silicium.git $MU
-git -C $MU checkout -q "$(cat BASE)"
-git -C $MU submodule update --init --recursive
-git -C $MU apply --whitespace=nowarn "$PWD/mu-silicium.patch"
-cp -r files/. $MU/
-echo "uefi/apply.sh: done; next: uefi/README.md"
+# The redwood platform on HakiOS's UEFI: uefi/apply.sh (Mu-Silicium with HakiOS's changes and banner), with this phone's
+# platform from files/ here. See README.md here for the vendor's drivers and the build.
+exec "$(dirname "$(readlink -f "$0")")/../../../uefi/apply.sh" redwood
diff --git a/devices/redwood/uefi/export.sh b/devices/redwood/uefi/export.sh
index 975afac..d75e70a 100755
--- a/devices/redwood/uefi/export.sh
+++ b/devices/redwood/uefi/export.sh
@@ -1,19 +1,13 @@
#!/bin/bash
-# Save our changes to the Mu-Silicium tree (../Mu-Silicium, a clone of Project-Silicium/Mu-Silicium
-# with the redwood port in it) into this directory: mu-silicium.patch for the files that upstream
-# has, files/ for the ones it does not. apply.sh puts them into a fresh clone.
+# Save the redwood platform from Mu-Silicium/ into files/ here (uefi/export.sh runs this; HakiOS's own changes are uefi/'s).
set -e
cd "$(dirname "$(readlink -f "$0")")"
-MU=../../../Mu-Silicium
-git -C $MU rev-parse HEAD > BASE
-git -C $MU diff -- BootShim Silicon > mu-silicium.patch
+MU=${MU:-../../../Mu-Silicium}
rm -rf files
-mkdir -p files/Resources/Configs files/Resources/DTBs files/Platforms/Xiaomi files/Binaries \
- files/Silicon/Silicium/SiliciumPkg/Library/BootManagerLib
+mkdir -p files/Resources/Configs files/Resources/DTBs files/Platforms/Xiaomi files/Binaries
cp -r $MU/Platforms/Xiaomi/redwoodPkg files/Platforms/Xiaomi/
cp $MU/Resources/Configs/redwood.toml files/Resources/Configs/
cp $MU/Resources/DTBs/redwood.dtb files/Resources/DTBs/
-cp $MU/Silicon/Silicium/SiliciumPkg/Library/BootManagerLib/XnuLoader.[ch] files/Silicon/Silicium/SiliciumPkg/Library/BootManagerLib/
cp -r $MU/Binaries/redwood files/Binaries/
find files -name __pycache__ -prune -exec rm -rf {} +
-echo "uefi/export.sh: base $(cut -c1-12 BASE), patch $(wc -l < mu-silicium.patch) lines, $(find files -type f | wc -l) files"
+echo "devices/redwood/uefi/export.sh: $(find files -type f | wc -l) files"
diff --git a/docs/boot-args.md b/docs/boot-args.md
index d6cc152..df76645 100644
--- a/docs/boot-args.md
+++ b/docs/boot-args.md
@@ -2,13 +2,13 @@
Made by `tools/boot-args.py --markdown`; CI fails if it is out of date with the source (`tools/boot-args.py --check`).
-Every argument that the kernel, the loader or user space of this port reads, and which file reads it. **316 arguments**: 267 read by the kernel, 14 by the loader, 44 by user space (one is read in more than one place).
+Every argument that the kernel, the loader or user space of this port reads, and which file reads it. **319 arguments**: 270 read by the kernel, 14 by the loader, 45 by user space (one is read in more than one place).
This is a catalogue of what exists and who reads it, not a manual. What an argument means is in the head of the file that reads it. The stable switches have a symbol in the configuration (`tools/hakios-config.py help SYMBOL`, `docs/configs.md`); the rest are the knobs of bring-up (a driver's steps, pauses, traces, test modes) and can change with the driver. Any of them can be given in a configuration with `CONFIG_BOOTARGS="name=value ..."`, which checks that each name is in this list.
Layers: **K** the kernel, **L** the loader, **U** user space (through `sysctl kern.bootargs`).
-## GPU and display (67)
+## GPU and display (68)
| Argument | Layer | Read by | Configuration | Set by |
|---|---|---|---|---|
@@ -69,6 +69,7 @@ Layers: **K** the kernel, **L** the loader, **U** user space (through `sysctl ke
| `gpu_exact` | K | `hakios.adreno.c` | `CONFIG_GPU_EXACT` | |
| `gpu_keep` | K | `hakios.gpu.cpp` | `CONFIG_GPU_KEEP` | |
| `gpu_log` | K | `hakios.adreno.c` | `CONFIG_GPU_LOG` | |
+| `metal` | KU | `HakiosMetal.m`, `MiniIOMobileFramebuffer.cpp` | `CONFIG_METAL` | |
| `rec_mb` | K | `MiniIOMobileFramebuffer.cpp` | `CONFIG_REC_MB` | |
| `rec_ring` | K | `MiniIOMobileFramebuffer.cpp` | `CONFIG_REC_RING` | |
| `rec_secs` | K | `MiniIOMobileFramebuffer.cpp` | `CONFIG_REC_SECS` | |
@@ -386,11 +387,13 @@ Layers: **K** the kernel, **L** the loader, **U** user space (through `sysctl ke
| `ufs` | L | `loader.c` | `CONFIG_UFS` | |
| `ufs_probe` | L | `loader.c` | `CONFIG_UFS_PROBE` | |
-## User space (13)
+## User space (15)
| Argument | Layer | Read by | Configuration | Set by |
|---|---|---|---|---|
| `autounlock` | U | `inject_sb.c` | `CONFIG_AUTOUNLOCK` | |
+| `bt` | K | `hakios.bt.c` | `CONFIG_BT` | |
+| `bt_again` | K | `hakios.bt.c` | `CONFIG_BT_AGAIN` | |
| `ca_vbl` | U | `inject.c` | `CONFIG_CA_VBL` | |
| `caenv` | U | `inject.c` | `CONFIG_CAENV` | |
| `cc_fade` | U | `inject_sb.c` | `CONFIG_CC_FADE` | |
diff --git a/docs/comparison.md b/docs/comparison.md
index 22b3e52..4d64a91 100644
--- a/docs/comparison.md
+++ b/docs/comparison.md
@@ -34,7 +34,7 @@ These are things that exist in this repository and that a reader can check:
"what exactly does this write to my phone?" is a file you can read ([legal-review.md](legal-review.md),
[LEGAL.md](../LEGAL.md)).
- **Its own loader, its own drivers**: GPU (Mesa over a Darwin driver), Wi-Fi, audio, haptics, cameras, touch, storage,
- modem bring-up. [driver-review/](driver-review) says what each is, and what has and has not been verified.
+ modem bring-up. [driver-review/](driver-review/README.md) says what each is, and what has and has not been verified.
## What the others have that this one does not
diff --git a/docs/concepts/architecture.md b/docs/concepts/architecture.md
new file mode 100644
index 0000000..3f4c824
--- /dev/null
+++ b/docs/concepts/architecture.md
@@ -0,0 +1,76 @@
+# Architecture
+
+HakiOS is three programs of its own between a phone's firmware and a user space: a UEFI application that loads the kernel, the
+kernel (Apple's XNU with this port), and the drivers inside it. Everything else is either the phone's (its UEFI, its firmware) or
+yours (the user space you lay out).
+
+## A boot, from the button to the home screen
+
+```
+ Android's fastboot HakiOS UEFI xnuloader XNU + HakiOS launchd user space
+ (the phone's own) --> (Mu-Silicium with --> (loader.efi, --> (xnu/, drivers/) --> --> (yours: iOS 16.5,
+ fastboot boot HakiOS's changes, xnuloader/) drivers started or userland/hello)
+ uefi/ + the device's) reads the payload by boot-arguments
+```
+
+| Step | What happens | Where it is |
+|---|---|---|
+| 1. into RAM | Android's fastboot receives a boot image and runs it; nothing is flashed | `./xl enter` |
+| 2. UEFI | HakiOS's UEFI (Mu-Silicium with HakiOS's changes and banner, and the phone's platform) starts on the SoC, shows the HakiOS logo, offers the framebuffer and storage, and starts the loader from the image | `uefi/`, `devices/<name>/uefi/` |
+| 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: iOS 16.5's (layer 2, yours), or `userland/hello` for the open kernel | `userland/` |
+
+## How a configuration becomes a kernel and a command line
+
+```
+ configs/common_defconfig (common)
+ socs/sc7280/configs/sc7280.config (SoC) make redwood_defconfig
+ devices/redwood/configs/redwood.config (device) -------------------------> .config
+ |
+ CONFIG_HAKIOS_* -> tools/hakios-config.py kernel -> XNU's options (config/MASTER.hakios, conf/files) -> make kernel
+ every other CONFIG_* -> tools/hakios-config.py args -> the kernel's boot-arguments -> make phone, ./xl run
+```
+
+Two kinds of symbol: `CONFIG_HAKIOS_<NAME>` decides whether a driver is compiled in, through XNU's own option mechanism; every other
+`CONFIG_` symbol is a boot-argument, because XNU takes its knobs from the command line. One `.config` gives both.
+[Configuration](../configs.md) and [Drivers in the configuration](../drivers-config.md) have the detail.
+
+## Common, SoC, device
+
+What is true of every device is the common repository's; what is true of a SoC family, the SoC's; what is true of one device, that
+device's. A device's defconfig is three lines: the common kernel, its SoC's fragment, its own.
+[How the repositories fit](../porting/repositories.md).
+
+| Layer | Has | Example |
+|---|---|---|
+| common | the kernel port, every driver, the loader, user space, the tools, the documentation | this repository |
+| SoC | the SoC's facts (cores, addresses that are the family's), its drivers | `socs/sc7280` |
+| device | its defconfig, its status, its UEFI platform, its firmware script, drivers of its own | `devices/redwood` |
+| UEFI | Mu-Silicium with HakiOS's boot path, banner and name | `uefi` ([its README](https://github.com/shimoku74/hakios/blob/main/uefi/README.md)) |
+
+## What is written to the phone
+
+| What | When | Where |
+|---|---|---|
+| the loader's log, a few KB | at the end of every run | the `logdump` partition |
+| `/private/var` | only with `ufs_write=1 var_store=1` | the partition `darwin`, which you create yourself (`tools/userdata-carve.py` prints the commands; it changes nothing) |
+| anything else | never | the loader refuses every other write; `tools/provenance.allow` lists each piece of code that can write, and why |
+
+[LEGAL.md](https://github.com/shimoku74/hakios/blob/main/LEGAL.md) has the same, with what is and is not distributed.
+
+## Where the code is
+
+| Directory | What |
+|---|---|
+| `xnu/` | the kernel: `hakios.patch` (Apple's files, changed), `files/` (new files), `apply.sh`, `export.sh` |
+| `drivers/<subsystem>/` | the drivers, by subsystem, each with its `conf` ([reference](../reference/drivers.md)) |
+| `xnuloader/` | the boot loader (a UEFI application, no EDK2) |
+| `userland/` | programs and libraries of our own (`src/`), the Metal plug-in, the image build, launchd jobs |
+| `configs/` | the common kernel's configuration and the generic fragments |
+| `socs/`, `devices/` | the SoC and device repositories, and `devices/manifest.conf` |
+| `sysimage/` | scripts that fetch and unpack the OS files from the IPSW (none of the files) |
+| `tools/` | configuration, devices, checks, APFS, firmware, QMI, the run scripts |
+| `qemu/` | running in QEMU |
+| `prebuilt/` | the kernel, loader and libraries built from this source |
diff --git a/docs/configs.md b/docs/configs.md
index 15dcb8c..b969c4d 100644
--- a/docs/configs.md
+++ b/docs/configs.md
@@ -2,8 +2,10 @@
A Linux kernel is configured with a `.config` made from a defconfig, and an Android kernel is put together from layers: the
common kernel's `gki_defconfig`, the SoC vendor's fragment, the device's. This kernel does the same, with one difference that
-is the whole design: **its options are not compiled in.** XNU takes them from the boot-arguments, so a configuration here is
-a file of `CONFIG_*` symbols that `tools/hakios-config.py` turns into the kernel's command line.
+is most of the design: **most of its options are not compiled in.** XNU takes them from the boot-arguments, so most of a
+configuration here is `CONFIG_*` symbols that `tools/hakios-config.py` turns into the kernel's command line. The exception is
+the drivers themselves: `CONFIG_HAKIOS_<NAME>` decides whether a driver is compiled into the kernel at all, through XNU's own
+`options` and `conf/files` ([drivers-config.md](drivers-config.md)), so that a device's defconfig builds the drivers that phone has.
```
configs/defconfig what every configuration starts from: the OPEN one (nothing of a phone's own, one core)
@@ -11,6 +13,7 @@ configs/common_defconfig THE COMMON KERNEL: every setting there is, each wi
configs/sc7280.config the Qualcomm SC7280 family (SM7325, QCM6490): eight cores, the sensors, the chip's identity
configs/redwood.config the POCO X5 Pro 5G: its vibration motor, where its modem's buffer is
configs/redwood_defconfig a phone: #include common_defconfig, sc7280.config, redwood.config (three lines)
+configs/qemu_defconfig QEMU's virt machine: the phone's drivers left out of the kernel (CONFIG_HAKIOS_*)
configs/open.config fragment: the open profile (CONFIG_FIRMWARE="none")
configs/virt.config fragment: QEMU's virt machine (virtio network)
configs/trace.config fragment: log a line for each of the first frames on the network interfaces
@@ -38,7 +41,8 @@ The same without make: `tools/hakios-config.py defconfig|merge|args|check|show|n
## What a symbol is
-`CONFIG_GPU=y` is the argument `gpu=1`; `CONFIG_CPUS=8` is `cpus=8`; `CONFIG_MODEM_BUFFER=0xa8000000` is
+`CONFIG_HAKIOS_GOODIX=y` is not an argument: it builds the touch driver into the kernel ([drivers-config.md](drivers-config.md)).
+Every other symbol is one: `CONFIG_GPU=y` is the argument `gpu=1`; `CONFIG_CPUS=8` is `cpus=8`; `CONFIG_MODEM_BUFFER=0xa8000000` is
`modem_buffer=0xa8000000`. A symbol that is `# CONFIG_X is not set` is left out, and the kernel's own default applies.
Three symbols are facts about the build, not arguments: `CONFIG_DEVICE`, `CONFIG_SOC` (it goes into the kernel's version
string, see [versioning.md](versioning.md)) and `CONFIG_FIRMWARE`.
@@ -63,11 +67,14 @@ each under a comment that says what it does, in groups (GPU and display, Wi-Fi,
thousand lines long, and why a reader of one file can see every setting the kernel has. It is made, not written:
```bash
-tools/hakios-config.py listing common > configs/common_defconfig # after changing a value or adding a driver
+tools/hakios-config.py listing common -o configs/common_defconfig # after changing a value or adding a driver
tools/hakios-config.py complete common # it must name every symbol (CI runs this, in the tests)
```
-Change a value by editing the line and running `listing common` again: the file reads back the same.
+Change a value by editing the line and running `listing common -o configs/common_defconfig` again: the file reads back the
+same. Not `listing common > configs/common_defconfig`: the shell empties the file before the tool reads it, and what is written is
+then `configs/defconfig` alone. That is how `common_defconfig` once lost the values of the phone line (the GPU, Wi-Fi, audio and
+modem switches, `CONFIG_FIRMWARE="device"`), and why `-o` exists.
## `#include`: putting a device together
@@ -102,24 +109,27 @@ word is `name=value` with no space, quote or backslash in it; and the words coun
| the common kernel | `gki_defconfig` | `common_defconfig` |
| a SoC, a device | vendor and device fragments, `build.config` | `sc7280.config`, `redwood.config`, `#include` |
| a fragment | `kernel/configs/*.config`, `merge_config.sh` | `configs/*.config`, `make NAME.config` |
-| the result | `.config`, compiled in | `.config`, becomes the boot-arguments |
+| the result | `.config`, compiled in | `.config`: the drivers compiled in (`CONFIG_HAKIOS_*`), the rest becomes the boot-arguments |
+| a driver's options | `Kconfig` + `obj-$(CONFIG_X) += x.o` | `drivers/<subsystem>/conf`, XNU's `options` and `optional` in `conf/files` |
| a minimal config | `make savedefconfig` | `make savedefconfig` |
| a command line baked in | `CONFIG_CMDLINE` | `CONFIG_BOOTARGS` (names checked) |
| an option that needs a blob | `CONFIG_EXTRA_FIRMWARE` | `CONFIG_FIRMWARE="device"` / `"none"`, and `needs` |
| the version | `uname -r` | `kern.hakios.version`, `kernel.ver=` |
| how many options | thousands, in Kconfig | about 310, one for each argument the source reads |
-The last row is the honest one. This is not Kconfig and has no thousand options: the kernel is not built from its options. The number
-of symbols is the number of arguments the code reads, and it grows when a driver adds one.
+The last row is the honest one. This is not Kconfig and has no thousand options: apart from which drivers it has, the kernel is not
+built from its options. The number of symbols is the number of arguments the code reads, plus one for each driver.
## A new device
`tools/new-device.py` makes `devices/<name>/` from a phone's own device tree. Its configuration is a fragment and a defconfig of a few
lines: `configs/<name>.config` with what is true of that phone only, and `configs/<name>_defconfig` that includes the common kernel, the
-SoC's fragment and that one, and nothing more until the phone has been shown to do it.
+SoC's fragment and that one, and nothing more until the phone has been shown to do it. The fragment is also where the phone leaves out
+the drivers of hardware it does not have or that has not been ported to it (`# CONFIG_HAKIOS_GOODIX is not set`: see
+[drivers-config.md](drivers-config.md)).
## What a configuration does not do
-It does not make a driver exist, and it does not make a driver work on a phone it was not written for. A symbol turns
-on a part of the kernel that is already there; whether it works on a given phone is what [the device's page](../devices)
+It does not make a driver exist, and it does not make a driver work on a phone it was not written for. A symbol builds
+in, or turns on, a part of the kernel that is already there; whether it works on a given phone is what [the device's page](../devices)
and the tests say, and the project does not claim a result it has not seen.
diff --git a/docs/devices/index.md b/docs/devices/index.md
new file mode 100644
index 0000000..aba898a
--- /dev/null
+++ b/docs/devices/index.md
@@ -0,0 +1,19 @@
+<!-- Made by tools/docs-gen.py from devices/*/device.conf and socs/*/soc.conf. Do not edit: change that, then run tools/docs-gen.py. -->
+
+
+# Devices
+
+Every device with a repository, and how far each part of it works. A device of yours: [Port a device](../porting/index.md).
+
+| Device | SoC | display | touch | buttons | cpu | gpu | storage | audio | battery | haptic | camera | torch | wifi | bluetooth | cellular | network | thermal |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| [QEMU virt (aarch64)](qemu.md) | `none` | yes | yes | yes | | no | yes | yes | | | | | | | | yes | |
+| [POCO X5 Pro 5G](redwood.md) | `sc7280` | yes | yes | yes | yes | yes | yes | yes | partly | yes | yes | partly | yes | no | partly | | partly |
+
+An empty cell is a part nobody has looked at on that device yet.
+
+## SoC families
+
+| SoC | What | |
+|---|---|---|
+| `sc7280` | Qualcomm SC7280 family (SM7325 "Snapdragon 778G", QCM6490; "yupik", "kodiak") | [`socs/sc7280/`](https://github.com/shimoku74/hakios/tree/main/socs/sc7280) |
diff --git a/docs/devices/qemu.md b/docs/devices/qemu.md
new file mode 100644
index 0000000..df26c0b
--- /dev/null
+++ b/docs/devices/qemu.md
@@ -0,0 +1,26 @@
+<!-- Made by tools/docs-gen.py from devices/qemu/device.conf. Do not edit: change that, then run tools/docs-gen.py. -->
+
+
+# QEMU virt (aarch64) (`qemu`)
+
+| | |
+|---|---|
+| Vendor | QEMU |
+| SoC | `none` |
+| Configuration | `make qemu_defconfig` |
+| Maintainer | the HakiOS developers (README.md) |
+| Repository | [`devices/qemu/`](https://github.com/shimoku74/hakios/tree/main/devices/qemu) |
+
+## What works
+
+| Part | State | |
+|---|---|---|
+| display | works | ramfb, through the loader |
+| touch | works | virtio tablet as the touch screen (CONFIG_HAKIOS_VIRTIO_INPUT) |
+| buttons | works | virtio keyboard: H is Home, L the power button, arrows the volume |
+| storage | works | virtio-blk images (CONFIG_HAKIOS_VIRTIO_BLK) |
+| audio | works | virtio sound (CONFIG_HAKIOS_VIRTIO_SOUND) |
+| network | works | virtio-net as en0 (CONFIG_HAKIOS_VIRTIO_NET) |
+| gpu | no | no GPU: the screen is drawn in software |
+
+The state is what has been seen on this device, written down in `devices/qemu/device.conf`; a part the table does not name has not been looked at.
diff --git a/docs/devices/redwood.md b/docs/devices/redwood.md
new file mode 100644
index 0000000..0a148b1
--- /dev/null
+++ b/docs/devices/redwood.md
@@ -0,0 +1,35 @@
+<!-- Made by tools/docs-gen.py from devices/redwood/device.conf. Do not edit: change that, then run tools/docs-gen.py. -->
+
+
+# POCO X5 Pro 5G (`redwood`)
+
+| | |
+|---|---|
+| Vendor | Xiaomi |
+| SoC | `sc7280` |
+| Configuration | `make redwood_defconfig` |
+| Maintainer | the HakiOS developers (README.md) |
+| Repository | [`devices/redwood/`](https://github.com/shimoku74/hakios/tree/main/devices/redwood) |
+| Firmware | `devices/redwood/pull-firmware.sh` pulls it from your own phone |
+
+## What works
+
+| Part | State | |
+|---|---|---|
+| display | works | the panel through UEFI's framebuffer; frames drawn by the GPU with gpu=1 |
+| touch | works | Goodix GT9916 / FocalTech FT3680 on SPI, multitouch (CONFIG_HAKIOS_GOODIX, touchscreen=1) |
+| buttons | works | power and volume through the PMIC (CONFIG_HAKIOS_BUTTONS) |
+| cpu | works | all 8 cores, the big core at 2.4 GHz (cpus=8 bootcpu=7 cpufreq=1) |
+| gpu | works | Adreno 642L, OpenGL ES through Mesa (gpu=1); Metal: buffers and libraries, no drawing yet |
+| storage | works | UFS read through the loader; /private/var kept with var_store=1 ufs_write=1 |
+| audio | works | speakers and microphone through the audio DSP (adsp=1 sound=4 mic=4) |
+| battery | partly | the level in the UI through the audio DSP; charging under this kernel is not done |
+| haptic | works | Awinic AW86927 (haptic=5) |
+| camera | works | Camera.app (cam=5) |
+| torch | partly | the PM8350C flash LED and Control Center's button (torch=N); not in the README's list of what works |
+| wifi | works | WCN6750 with Linux's ath11k: radio, driver, a network joined (wifi=1) |
+| bluetooth | no | step one only: a read-only look at its pins (bt=1) |
+| cellular | partly | the modem boots, sees the network, the SIM is bound, IPA and en1 in place; no registration yet |
+| thermal | partly | 27 of 27 sensors read on the phone (thermal=1); the stop (thermal_stop=) not yet seen firing |
+
+The state is what has been seen on this device, written down in `devices/redwood/device.conf`; a part the table does not name has not been looked at.
diff --git a/docs/driver-review/sound.md b/docs/driver-review/sound.md
index 5c73fdc..2732e02 100644
--- a/docs/driver-review/sound.md
+++ b/docs/driver-review/sound.md
@@ -256,7 +256,7 @@ userland/src/audio_plugin.c
## Fix status
-Edits only in drivers/audio/hakios.{audio,sound,speaker,mic,virtio_sound}.c and drivers/storage/hakios.guard.c. Nothing was compiled or run.
+Edits only in drivers/audio/hakios.{audio,sound,speaker,mic,virtio_sound}.c and drivers/audio/hakios.guard.c (then in drivers/storage/). Nothing was compiled or run.
- S-01 FIXED. Three layers: audio.c audio_ioctl clamps the user's `below` to HAKIOS_AUDIO_BELOW_MAX (90 * 8 = speaker.c VOLUME_LOWEST, the documented "sound_below=720" floor); sound.c watch() now uses a saturating below_with(extra) instead of `below + extra` (three places), and guard_level() never passes a level equal to the HAKIOS_GUARD_SILENT sentinel; speaker.c hakios_speaker_volume() clamps `below` to VOLUME_LOWEST before `volume_at + below`, so the fade loop's target can no longer wrap under volume_at and the loop always ends. guard.c block(): `2 * attenuation` no longer wraps in 32 bits (the blind-guard range from item 5). Not done: an iteration limit on the fade loop (not needed once the target is in range) and a guard_level() clamp beyond the sentinel one.
- S-02 FIXED with S-01 (clamp of `extra` in audio.c, saturating sum in sound.c).
diff --git a/docs/drivers-config.md b/docs/drivers-config.md
new file mode 100644
index 0000000..9498751
--- /dev/null
+++ b/docs/drivers-config.md
@@ -0,0 +1,144 @@
+# Drivers in the configuration: what the kernel is built with
+
+A Linux kernel builds a driver when its `Kconfig` symbol is on: `drivers/input/touchscreen/Kconfig` declares
+`TOUCHSCREEN_GOODIX`, the directory's `Makefile` says `obj-$(CONFIG_TOUCHSCREEN_GOODIX) += goodix.o`, and a device's defconfig
+(`arch/arm64/configs/vendor/<device>_defconfig` in an Android kernel) turns on what that phone has. Every phone vendor's tree is
+that, with its own drivers added the same way.
+
+This kernel is Apple's XNU, which has the same idea under other names, much older than Kconfig: `config/MASTER` declares the
+**options** (`options APFS # <apfs>`), a component's `conf/files` lists its files as `standard` or `optional <option>`, and a
+configuration (`DEVELOPMENT = [ ... ]` in `MASTER.<arch>.<platform>`) is the list of what is on; `SETUP/config/doconf` and
+`config(8)` turn that into the list of objects and `-D<OPTION>` for the compiler. The drivers of this port are XNU options of
+that kind. Nothing here imitates Kconfig's files; what a driver is, is written once per subsystem, in `drivers/<subsystem>/conf`.
+
+```
+drivers/<subsystem>/conf the drivers of a subsystem: their files, what they require, what they are
+configs/*_defconfig CONFIG_HAKIOS_<NAME>=y or `# CONFIG_HAKIOS_<NAME> is not set`, beside the boot-argument symbols
+tools/hakios-config.py kernel the choice of the .config put into the kernel tree (make kernel runs it)
+```
+
+## `drivers/<subsystem>/conf`
+
+```
+standard bsd/dev/hakios.input.c
+ help /dev/hakios-touch, the queue of touches and buttons, and where the phone's drivers are started from
+
+driver GOODIX
+ file bsd/dev/hakios.goodix.c
+ help the touch screen: a Goodix GT9916 or a FocalTech FT3680 on SPI (touchscreen=1) ...
+
+driver SOUND
+ file bsd/dev/hakios.sound.c
+ file bsd/dev/hakios.guard.c
+ requires ADSP SPEAKER
+ help the speakers playing (sound=N) ...
+```
+
+| Word | Means |
+|---|---|
+| `standard PATH [OPTION...]` | a file every kernel has (with XNU options of its own, if given: `hakios.apfs_check.c apfs`) |
+| `driver NAME` | the symbol `CONFIG_HAKIOS_NAME`, the XNU option `HAKIOS_NAME`, the attribute `hakios_name` |
+| `file PATH [OPTION...]` | one of its files, as its path in Apple's tree; a `.cpp` of `iokit/Kernel` also wants `iokitcpp` |
+| `requires NAME...` | drivers it cannot be built without (it calls them, and nothing could stand in for them) |
+| `default y\|n` | what a configuration that does not name it gets; `y` if not said |
+| `help TEXT` | what it is, and which boot-argument starts it; more `help` lines go on |
+
+Every `.c` and `.cpp` of `drivers/map` is built by exactly one `standard` line or `driver`, of the conf of its own subsystem;
+`tools/drivers-check.py` (CI) checks that, and a file that none builds would be in the tree and never compiled.
+
+The 25 drivers there are now, by subsystem:
+
+| Subsystem | Drivers (`CONFIG_HAKIOS_*`) | Always built |
+|---|---|---|
+| core | `SOCINFO` | `hakios.version.c`, `hakios.platform.c`, `hakios.stubs.c` |
+| input | `VIRTIO_INPUT`, `GOODIX`, `BUTTONS` | `hakios.input.c` |
+| storage | `UFS`, `VIRTIO_BLK` | `hakios.image.c`, `hakios.sparse.c`, `hakios.apfs_check.c` |
+| gpu | `ADRENO` | |
+| camera | `CAMERA`, `TORCH` | |
+| haptic | `HAPTIC` | |
+| audio | `ADSP`, `SPEAKER`, `SOUND` (requires ADSP, SPEAKER), `MIC` (requires ADSP, SOUND), `VIRTIO_SOUND` | `hakios.audio.c` |
+| power | `BATTERY`, `CPUFREQ`, `THERMAL`, `PMIC`, `BATTGUARD` | |
+| wifi | `WIFI` (requires QMI) | |
+| bluetooth | `BT` | |
+| modem | `QMI`, `MODEM` (requires QMI, UFS) | |
+| net | `VIRTIO_NET` | `hakios.net.c` |
+
+`tools/hakios-config.py help HAKIOS_SOUND` says the same of one of them, and what requires it.
+
+## A device's defconfig chooses its drivers
+
+A driver nobody names is built (`default y`): every driver was built before there were these symbols, and a `.config` made
+then still gives the same kernel. A device leaves out what it does not have:
+
+```
+# configs/qemu_defconfig (in the tree): QEMU's virt machine, the phone's drivers left out of the kernel
+#include common_defconfig
+#include open.config
+#include virt.config
+CONFIG_DEVICE="qemu"
+# CONFIG_HAKIOS_GOODIX is not set
+# CONFIG_HAKIOS_ADRENO is not set
+...
+```
+
+```bash
+make qemu_defconfig # .config: 4 drivers built in (the virtio ones), 21 left out
+make config # says which are built and which are not
+make kernel # builds that kernel
+```
+
+A port to another phone starts the same way: its `configs/<name>.config` leaves out each driver whose hardware it has not
+ported yet (the addresses and pins in a driver are the POCO X5 Pro's, and its head says where each came from), and turns one
+on when it has been made to work there. A phone with another touch controller adds a driver, not a branch: its file in
+`drivers/input/`, a line in `drivers/map`, a `driver` block in `drivers/input/conf`, and `CONFIG_HAKIOS_<IT>=y` in its defconfig.
+
+### What is checked
+
+- `# CONFIG_HAKIOS_X is not set` means **left out**, not "the default": a fragment can take a driver out of a configuration
+ that an earlier file put it in, as in Linux.
+- A driver built without one it `requires` is refused: `CONFIG_HAKIOS_SOUND requires CONFIG_HAKIOS_ADSP (drivers/audio/conf:13)`.
+- A boot-argument that only left-out drivers read is refused, with the driver named:
+ `CONFIG_TOUCHSCREEN gives touchscreen=, which only hakios.buttons.c, hakios.goodix.c read, and they are not built
+ (CONFIG_HAKIOS_BUTTONS, CONFIG_HAKIOS_GOODIX)`. The kernel would not complain: the argument would just never be looked at.
+ (The readers are found the way `tools/boot-args.py` finds them, in the source.)
+
+## How the choice reaches XNU's build
+
+`tools/hakios-config.py kernel` (run by `make kernel` through `tools/make-kernel.sh`, and by `xnu/apply.sh`) writes, into the
+kernel tree, only what has changed:
+
+| File in the tree | What | In `xnu/hakios.patch`? |
+|---|---|---|
+| `bsd/conf/files`, `iokit/conf/files` | one block between `# HakiOS drivers: ...` and `# end of the HakiOS drivers`: each file `standard` or `optional hakios_<name>` | yes: it does not depend on the configuration |
+| `config/MASTER.hakios` | `# HAKIOS_DRIVERS = [ hakios_goodix ... ]` (the attributes that are on) and an `options HAKIOS_<NAME> # <hakios_<name>>` line for every driver | no: made for each build, kept out by `xnu/export.sh` |
+| `bsd/dev/hakios.drivers.h` | the list, for `sysctl kern.hakios.drivers` and the boot log line `hakios-kernel: N drivers built in` | no |
+
+and what the patch carries once: `SETUP/config/doconf` reads `MASTER.hakios` after `MASTER` and `MASTER.arm64.bcm2837`; the
+kernel configurations of `MASTER.arm64.bcm2837` (`RELEASE`, `DEVELOPMENT`, `DEBUG`, `KASAN`) include `HAKIOS_DRIVERS`; each
+component's `conf/Makefile` makes its configuration again when `MASTER.hakios` changes. XNU's build passes the options as
+`-DHAKIOS_<NAME>` in the compiler's command line rather than as a file an object depends on, so when the choice changes,
+`kernel` also removes the objects of the files that ask about it (`#ifdef HAKIOS_*`): they are built again.
+
+Linux's `ath11k` object (`tools/mk-ath11k.sh`) is linked in only with `CONFIG_HAKIOS_WIFI` (`xnu-build.sh`): its calls are
+answered by `hakios.lx.c`.
+
+## Leaving a driver out without breaking the others
+
+The rest of the kernel calls the drivers in a few places: where they are started (`hakios.input.c`, `hakios.audio.c`,
+`bsd_init.c`), where a run ends or a panic leaves (`loader_return.c`, the thermal and battery guards, `machine_routines.c`),
+and a few questions on the way ("is this device one of the storage's?", "how warm is the battery?"). Those calls stay as they
+are. For a driver that is left out, `drivers/core/hakios.stubs.c` (XNU keeps `bsd/kern/bsd_stubs.c` for the same purpose) has
+what each such call then does: nothing, and the answer "no", "not known" or "not there". With every driver built it compiles to
+nothing, so the phone's kernel is the one it was.
+
+What several drivers share was moved where none of them owns it, `drivers/core/hakios.platform.c`: the PMIC arbiter's lock
+(from `hakios.buttons.c`), the locks of the always-on processor's mailbox, the shared memory's allocation, RPMh and the SMMU
+(from `hakios.wifi.c`), and the `kern.hakios` sysctl node (from `hakios.battery.c`). Before, the camera could not be linked
+without the Wi-Fi driver, and every driver's sysctls without the battery's. The camera's and the motor's firmware is read with
+`hakios_image_file()` directly instead of through the Wi-Fi driver.
+
+## What was checked
+
+On a Mac (Apple clang, the toolchain of `xnu-deps/`), 27 October 2026: the kernel built and linked with every driver
+(`make kernel` without a `.config`), and with `make qemu_defconfig`, four drivers of 25. The QEMU kernel was not booted yet,
+and nothing here was run on the phone. `tools/hakios-config-test.py` and `tools/drivers-check.py` pass.
diff --git a/docs/getting-started/building.md b/docs/getting-started/building.md
new file mode 100644
index 0000000..15aebe7
--- /dev/null
+++ b/docs/getting-started/building.md
@@ -0,0 +1,74 @@
+# Building from source
+
+`prebuilt/` has what most people need. Build when you change something, and to check that the source is what was shipped.
+
+## The kernel
+
+Apple's XNU sources (the release iOS 16.5 was built from) with this port laid over them:
+
+```sh
+make redwood_defconfig # or any device's defconfig; without a .config every driver is built
+make kernel # xnu/apply.sh (once), xnu-deps/setup.sh (once), then the build
+```
+
+`make kernel` is `tools/make-kernel.sh`: it copies the drivers you edited into the tree (`xnu/sync-drivers.sh`), puts the
+configuration's choice of drivers where XNU's build reads it (`tools/hakios-config.py kernel`), builds, and judges the result by
+what failed rather than by the exit status (the last steps of XNU's own build always fail on this machine configuration, for kext
+symbol sets this kernel does not have; any other failure is a failure). The kernel is
+`xnu-src/xnu-8796.121.2/BUILD/obj/DEVELOPMENT_ARM64_BCM2837/mach.development.bcm2837`.
+
+| Host | Toolchain |
+|---|---|
+| Linux | theos with its cctools and `iPhoneOS16.5.sdk`; `xnu-deps/setup.sh` lays it out |
+| macOS | Xcode or the command-line tools; the SDK is fetched for you |
+
+### Changing the kernel
+
+The kernel's changes live in this repository in two forms: `xnu/hakios.patch` (Apple's files, changed) and `xnu/files/` (new
+files), with the drivers by subsystem in `drivers/`. Work in the tree (`xnu-src/xnu-8796.121.2`), then save it:
+
+```sh
+xnu/export.sh # the tree -> xnu/hakios.patch, xnu/files/, drivers/
+python3 tools/drivers-check.py # drivers/map and drivers/*/conf agree
+```
+
+A driver you edit in `drivers/` goes into the tree by itself on the next `make kernel`.
+
+## The loader
+
+```sh
+make loader # xnuloader/build.sh: clang and lld-link, an EFI application without EDK2
+```
+
+The header `xnuloader/identity.h`, the properties by which iOS tells which iPhone it is, is not kept in the repository:
+`xnuloader/mkidentity.sh` makes it at build time from the device tree in your own IPSW. `make loader-open` makes the placeholder
+loader that boots the open kernel only.
+
+## User space and the images
+
+```sh
+REST=1 userland/build.sh # programs, libraries, the Metal plug-in, the APFS images
+GL=1 REST=1 userland/build.sh # ... with Mesa, for gpu=1
+```
+
+`MODEM=1 SYSTEM=1` put the modem's firmware into the system image.
+
+## The checks
+
+What CI runs, and what to run before a pull request:
+
+```sh
+python3 tools/hakios-config-test.py # configurations, drivers' choice
+python3 tools/hakios-device-test.py # SoC and device repositories
+python3 tools/hakios-device.py check # every device and SoC checked out holds together
+python3 tools/drivers-check.py # drivers/map, drivers/*/conf
+python3 tools/boot-args.py --check # the boot-argument catalogue is current
+python3 tools/docs-gen.py --check # the made documentation pages are current
+python3 tools/docs-check.py # every link of the documentation goes somewhere
+python3 tools/provenance-check.py # nothing in the tree that must not be
+sh tools/metallib-test.sh # the Metal plug-in's metallib reader, under sanitizers
+tools/metal-plugin-test.sh # (macOS) the Metal plug-in's objects on the Mac's own Metal
+```
+
+`python3 tools/docs-check.py` checks that every link of the documentation goes somewhere. The website (`hakios-web`) shows these
+same pages; its `npm run docs` takes them from this repository.
diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md
new file mode 100644
index 0000000..3f6be2d
--- /dev/null
+++ b/docs/getting-started/index.md
@@ -0,0 +1,29 @@
+# Getting started
+
+Three ways in, from the one that needs nothing to the one that needs a phone. Each page says what you need, what to run, what you
+should see, and what to check when you do not see it.
+
+| | What you get | What you need | Time |
+|---|---|---|---|
+| [**The open kernel in QEMU**](qemu.md#the-open-kernel) | the kernel, the loader and a tiny user space, booting | a Linux or macOS machine, QEMU | minutes |
+| [**iOS in QEMU**](qemu.md#ios-in-qemu) | the lock screen and the home screen in a window | Linux, 12 GB of disk, Apple's IPSW (downloaded for you) | an hour, mostly downloads |
+| [**On the phone**](phone.md) | the system on a POCO X5 Pro 5G, in RAM | the phone, its boot loader unlocked, `adb` and `fastboot` | an hour the first time |
+
+Building from source is optional for all three: `prebuilt/` has a kernel, a loader and libraries made from these repositories.
+[Building from source](building.md) when you change something.
+
+## Your machine
+
+| Host | What works | Notes |
+|---|---|---|
+| Linux x86-64 | everything | the reference: CI runs here |
+| macOS (Apple silicon) | building the kernel, the loader, user space; the tests | QEMU from Homebrew for running; the phone through `adb`/`fastboot` |
+| Windows | everything, split between WSL 2 and Git Bash | [Windows](../windows.md) says what runs where |
+
+`make doctor` checks the machine (and a phone on `adb`) for what HakiOS needs, and says what to install.
+
+## Where to go next
+
+- [Architecture](../concepts/architecture.md): how a boot goes, from UEFI to the home screen, and which part does what.
+- [Configuration](../configs.md): defconfigs, fragments, and what a `CONFIG_` symbol turns into.
+- [Port a device](../porting/index.md): your own phone, step by step.
diff --git a/docs/getting-started/phone.md b/docs/getting-started/phone.md
new file mode 100644
index 0000000..4e22726
--- /dev/null
+++ b/docs/getting-started/phone.md
@@ -0,0 +1,68 @@
+# On the phone
+
+The phone with a port today is the **POCO X5 Pro 5G** (`redwood`, Snapdragon 778G): [its page](../devices/redwood.md). Another
+phone needs a port first: [Port a device](../porting/index.md).
+
+## What happens to the phone
+
+Nothing is installed. The loader goes into RAM with `fastboot boot`, the system image is sent into RAM, a session runs for as long
+as you say, 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 phone's `logdump` partition. With `ufs_write=1` (off unless you ask) the kernel writes to a partition named `darwin`
+that you create yourself, and nowhere else. [What is written, exactly](../concepts/architecture.md#what-is-written-to-the-phone).
+
+## What you need
+
+- the phone, its boot loader unlocked;
+- `adb` and `fastboot` on the PC (Google's platform-tools; on Windows, see [Windows](../windows.md));
+- the images of [iOS in QEMU](qemu.md#ios-in-qemu) (`userland/system.apfs`), and `make loader` done once;
+- the phone's own firmware, pulled from it (below). It is the vendor's and is never in the repositories.
+
+## Step by step
+
+```sh
+devices/redwood/pull-firmware.sh # Android running, on adb: GPU, Wi-Fi, audio, haptics, modem, cameras -> fw-*/
+make redwood_defconfig # the phone's configuration: the common kernel, the SC7280's, the phone's own
+make config # what it is: the drivers built in, the kernel's arguments, the firmware it wants
+make phone SECS=600 # a 10-minute session with the .config's arguments
+```
+
+`make phone` checks the `.config` and runs `tools/modem-cycle.sh`: it waits for the phone, enters the loader, uploads the system
+image, runs the kernel with the configuration's arguments and summarises the log in `logs/`. The phone is never flashed. It is left in our
+loader for the next run; `XL_END=android make phone ...` sends it back to Android at the end.
+
+The same by hand, one step at a time:
+
+```sh
+./xl enter # Android -> fastboot -> our loader in RAM
+./xl ramdisk userland/system.apfs # the system image into the phone's RAM (about 80 s), once per loader session
+XL_SECS=600 XL_CMDLINE="$(tools/hakios-config.py args)" ./xl run # a session; the log goes to logs/
+./xl reboot # back to Android
+```
+
+## The arguments that matter
+
+A configuration sets them for you (`CONFIG_GPU=y` is `gpu=1`); [every argument](../boot-args.md) is listed with what reads it.
+
+| Argument | What it does |
+|---|---|
+| `cpus=8 bootcpu=7 cpufreq=1` | all eight cores, the biggest one at full speed |
+| `touchscreen=1` | the touch screen and the buttons |
+| `gpu=1` | rendering on the Adreno (an image built with `GL=1`, firmware in `fw-gpu/`) |
+| `adsp=1 sound=4 mic=4` | the audio DSP: speakers, microphone; the battery's level comes with it |
+| `haptic=5` | the vibration motor |
+| `wifi=1` | Wi-Fi (the network from `fw-wifi/network`) |
+| `cam=5` | the cameras |
+| `modem=1` | the modem: its firmware, file systems, data path, SIM ([cellular](../cellular.md)) |
+| `var_store=1 ufs_write=1` | keep `/private/var` across reboots (**writes** to the partition `darwin`) |
+| `thermal=1 thermal_stop=105` | read the temperatures (the SC7280's fragment sets `thermal=1`); hand back to the loader at 105 °C (not set by default) |
+| `battery_stop=15` | hand back to the loader before the battery is flat |
+
+## When something goes wrong
+
+| You see | Do |
+|---|---|
+| a session that does not end | `./xl` leaves its log in `logs/` and brings the phone back from the boot loader, or tells you which keys to press |
+| the phone getting hot | `thermal_stop=105` (`CONFIG_THERMAL_STOP=105`) hands control back to the loader at that temperature; it is **not** set by default |
+| a run left alone on battery | `battery_stop=<percent>` ends it before the battery is flat |
+| a problem in `make config` | it names the symbol and why: a driver left out that an argument needs, firmware the open profile does not load |
+| anything else | the log in `logs/`, and `make doctor` with the phone on `adb` |
diff --git a/docs/getting-started/qemu.md b/docs/getting-started/qemu.md
new file mode 100644
index 0000000..d6e24b7
--- /dev/null
+++ b/docs/getting-started/qemu.md
@@ -0,0 +1,64 @@
+# QEMU
+
+## The open kernel
+
+The kernel, a placeholder loader and a tiny raw-syscall user space: **nothing of Apple's and nothing of any phone's**.
+
+```sh
+git clone https://github.com/shimoku74/hakios.git hakios
+cd hakios
+make doctor # what this machine lacks, and what to do
+make qemu-open # builds what is missing, then boots
+```
+
+What you should see in the log: `== XNULOADER v3 ==`, the kernel's banner with `hakios-kernel: version ...`, the drivers built in
+(`hakios-kernel: N drivers built in (...)`), and the user space's own lines. `make qemu-open` uses `configs/defconfig`; with
+`make qemu_defconfig` first, the kernel is built with only QEMU's drivers in it ([devices/qemu](../devices/qemu.md)).
+
+## iOS in QEMU
+
+Linux x86-64, about 12 GB of disk, 7-Zip 23 or newer, `lz4`, `qemu-system-aarch64`, `edk2-aarch64`.
+
+```sh
+make doctor # QEMU's display device, UEFI firmware, memory: what is missing, and what to do
+sysimage/fetch.sh # the iOS 16.5 IPSW from Apple's servers, the needed parts unpacked (7.4 GB)
+REST=1 userland/build.sh # the APFS images: userland/root.apfs and userland/system.apfs
+make loader # the boot loader, with the iPhone's identity taken from YOUR copy of the IPSW
+mkdir -p logs
+qemu/run-ios.sh 1200 -display gtk > logs/qemu.log # a 20-minute session
+```
+
+`make loader` is not optional here: `prebuilt/loader.efi` has no Apple data in it on purpose and boots the open kernel only.
+`qemu/run-ios.sh` refuses to start without your own `xnuloader/loader.efi`, and says so.
+
+### What you will see
+
+The CPU is emulated, so it is slow, and **the window is black at first**: that is normal. On a fast desktop: black for the first
+minute, the Apple logo at about one minute, the home screen at about five. Longer on a slower machine.
+
+| Input | Is |
+|---|---|
+| the mouse, with the button held | a finger |
+| `H` | Home |
+| `L` | the power button |
+| `↑` `↓` | volume |
+
+### If it stays black
+
+Check these in order.
+
+1. **The log.** `tail -f logs/qemu.log` in another terminal. It should print `== XNULOADER v3 ==` within seconds, and kernel and
+ launchd lines after that. Nothing at all: QEMU did not start the loader; run `make doctor`.
+2. **An old loader.** A log with `ramfb: control ... after the request` near its top is a loader built before 27 October 2026 (a
+ compiler could skip the check of the display request): the window stays at 800x600 and iOS draws outside it. `make loader` again.
+3. **What the guest shows.** `qemu/screendump.sh` saves the guest's screen to `logs/qemu-screen.png`, whatever your window does.
+4. **No window.** Your QEMU may have no GTK window (a headless package, WSL without WSLg). Use
+ `qemu/run-ios.sh 1200 -display vnc=127.0.0.1:0 > logs/qemu.log` and a VNC viewer on `127.0.0.1:5900`.
+5. **Memory.** The guest asks for 7 GB (`QEMU_RAM_GB`; 6 at the very least: the system image sits 3 GB into it and is 2.5 GB).
+ Without that the host swaps and everything is very slow.
+6. **The images.** `qemu/run-ios.sh` needs `userland/system.apfs` and `userland/root.apfs`; a missing one is reported at once.
+
+## Metal in QEMU
+
+`RC_JOBS=rc.jobs.metal` with the boot argument `metal=1` runs `metal_test`, which prints what iOS believes about Metal, what the
+device makes (buffers, a library) and what CoreImage does. [The Metal plan](../metal-plan.md) has what each line means.
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..de0f0dc
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,53 @@
+# HakiOS
+
+**Apple's open-source Darwin kernel (XNU) on Android phones with a Qualcomm SoC**, 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 to start:
+
+- [Getting started](getting-started/index.md): the open kernel in QEMU in a few commands, or the iOS 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.
+- [Reference](reference/drivers.md): every driver, configuration symbol and boot argument, made from the source.
+
+## What works
+
+The table is made from the devices' own `device.conf`: [all devices](devices/index.md).
+
+| | POCO X5 Pro 5G (`redwood`) | QEMU `virt` |
+|---|---|---|
+| Lock screen, home screen, the stock apps | yes | yes (slow: the CPU is emulated) |
+| Touch, buttons | yes | yes (the mouse and the keyboard) |
+| GPU (OpenGL ES through Mesa) | yes | no |
+| Metal | partly: a device that Metal loads (seen in QEMU); buffers and libraries written, checked on a Mac only; nothing drawn ([plan](metal-plan.md)) | partly, the same |
+| Wi-Fi | yes | yes (virtio-net) |
+| Sound, microphone | yes | sound only (virtio) |
+| Cameras, vibration | yes | no |
+| Flashlight, temperature guard | partly: written, some of it seen ([redwood](devices/redwood.md)) | no |
+| Cellular | partly: the modem is up and sees the network; no registration yet ([cellular](cellular.md)) | no |
+| Bluetooth | 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 you supply; it was built so that it can start iOS 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.
+
+By default nothing is installed: the loader goes into RAM, the system lives in RAM for a session, a reboot gives the phone back to
+Android. What is and is not written to a phone: [Architecture](concepts/architecture.md#what-is-written-to-the-phone).
+
+## The repositories
+
+| Repository | What |
+|---|---|
+| [hakios](https://github.com/shimoku74/hakios) | **common**: the kernel port, the drivers, the loader, user space, the tools, this documentation |
+| `socs/sc7280` | the Qualcomm SC7280 family (Snapdragon 778G): its configuration fragment and drivers |
+| `devices/redwood` | POCO X5 Pro 5G: its defconfig, UEFI port, firmware script, status |
+| `devices/qemu` | QEMU's `virt` machine, as a device |
+
+SoC and device repositories are kept in the common tree until they are split into their own; `devices/manifest.conf` lists them
+all, and `tools/hakios-device.py sync` fetches the ones that live elsewhere. [How the repositories fit](porting/repositories.md).
diff --git a/docs/porting/drivers.md b/docs/porting/drivers.md
new file mode 100644
index 0000000..4f3aef7
--- /dev/null
+++ b/docs/porting/drivers.md
@@ -0,0 +1,95 @@
+# Writing a driver
+
+A driver here is one or more C or C++ files of the kernel, a block in a `conf` file that makes it a configuration symbol, and a
+boot-argument that starts it. This page goes through adding one; [Drivers in the configuration](../drivers-config.md) is the
+reference for the mechanism.
+
+## Where it goes
+
+| The driver is | Put it in |
+|---|---|
+| for hardware many devices share, or a SoC family's | the common repository: `drivers/<subsystem>/` |
+| one device's own (a touch controller only it has) | that device's repository: `devices/<name>/drivers/<subsystem>/` |
+| a SoC family's own | `socs/<soc>/drivers/<subsystem>/` |
+
+Subsystems: input, storage, gpu, camera, haptic, audio, power, wifi, bluetooth, modem, net, core.
+
+## 1. The file
+
+`hakios.<name>.c` (or `.cpp` for an IOKit service). The head says what it is, where every address and number came from (the
+device tree, the vendor's Linux driver, a measurement), and what has been seen working:
+
+```c
+/*
+ * The touch screen of the My Phone (mydevice): a Novatek NT36672 on I2C 2, as a source of touches for /dev/hakios-touch
+ * (sys/hakios.input.h). Only with boot-arg touchscreen=1.
+ *
+ * Where the numbers come from: the phone's device tree (i2c@988000, novatek,nt36xxx), Novatek's Linux driver ...
+ *
+ * Status: written, not yet run.
+ */
+#include <pexpert/pexpert.h>
+#include <sys/hakios.input.h>
+
+void
+hakios_nt36672_init(void)
+{
+ uint32_t enabled = 0;
+
+ if (!PE_parse_boot_argn("touchscreen", &enabled, sizeof(enabled)) || !enabled) {
+ return; /* nothing is touched unless a boot-argument asks */
+ }
+ /* ... hakios_touch_post(HAKIOS_TOUCH_DOWN, finger, x, y) for each sample ... */
+}
+```
+
+Rules every driver here follows:
+
+- **nothing happens without its boot-argument**; a driver that is built in and not asked for touches no register;
+- every value read from the phone is checked before it is used: a length, an offset, an index;
+- a step that fails says which, in one log line, and the driver stops rather than guessing;
+- writes to a PMIC or to storage are the exception, and are listed in `tools/provenance.allow` with why.
+
+## 2. Make it a symbol
+
+In the `conf` of its subsystem (common: `drivers/input/conf`; a device's: `devices/<name>/drivers/input/conf`):
+
+```
+driver NT36672
+ file bsd/dev/hakios.nt36672.c
+ help the touch screen of the My Phone: a Novatek NT36672 on I2C (touchscreen=1)
+```
+
+`file` is the file's place in Apple's tree: `bsd/dev/` for C, `iokit/Kernel/` for C++ (with `iokitcpp`). `requires` names
+drivers it cannot be built without.
+
+A common driver is also a line of `drivers/map` (`input bsd/dev/hakios.nt36672.c`); a device's is not, it is found by its conf.
+
+## 3. Start it
+
+Drivers are started in one of two ways:
+
+- by XNU's own initcall, `STARTUP(EARLY_BOOT, STARTUP_RANK_LAST, my_init);` at the end of the file. Nothing else to change; this
+ is how `socinfo`, `thermal`, `pmic`, `battguard` and `bt` start. **Prefer this for a new driver.**
+- from a hub's list (`hakios_input_init()` in `hakios.input.c`, `hakios_audio_init()` in `hakios.audio.c`), when the order
+ matters. Then the hub calls it whether or not it is built: give it a stand-in in `drivers/core/hakios.stubs.c`
+ (`#ifndef HAKIOS_NT36672 void hakios_nt36672_init(void) {} #endif`), or the kernel will not link without it.
+
+## 4. Build it, check it
+
+```sh
+echo CONFIG_HAKIOS_NT36672=y >> devices/mydevice/configs/mydevice.config
+make mydevice_defconfig && make kernel
+python3 tools/drivers-check.py # (common drivers) the map and the conf files agree
+tools/hakios-device.py check mydevice # (a device's) its files are there
+python3 tools/boot-args.py --check # a new boot-argument is in the catalogue: run without --check to add it
+python3 tools/docs-gen.py # the reference page
+```
+
+The boot log says `hakios-kernel: N drivers built in (... nt36672 ...)`, and `sysctl kern.hakios.drivers` the same.
+
+## 5. Write down what it does
+
+The driver's head says what has been seen (on the phone, in QEMU, compiled only). The device's `device.conf` has a `status` line
+for the part it makes work. [docs/driver-review](https://github.com/shimoku74/hakios/tree/main/docs/driver-review)
+holds the audits of the common drivers: a new common driver gets one before it is relied on.
diff --git a/docs/porting/index.md b/docs/porting/index.md
new file mode 100644
index 0000000..a65a4ec
--- /dev/null
+++ b/docs/porting/index.md
@@ -0,0 +1,97 @@
+# Port a device
+
+What it takes to bring HakiOS to a phone that does not have it yet, in the order that works: first a repository and a
+configuration, then a boot with nothing of the phone's, then the drivers one at a time. Each step says how you know it is done.
+
+> **Before you start.** A port runs from RAM and writes nothing by default, but you are working on a phone's hardware. Read
+> [What is written to the phone](../concepts/architecture.md#what-is-written-to-the-phone), keep a way back to Android
+> (`fastboot` and the stock images), and pull the phone's firmware before anything else.
+
+## What you need
+
+- a phone with an ARM64 Qualcomm SoC, its boot loader unlocked; a UEFI port for it (a Mu-Silicium port, as `devices/redwood/uefi` is, or your own);
+- the phone's own device tree (`adb shell` with root, or from its boot image) and its Android running, for the firmware;
+- a machine that builds the kernel ([Building from source](../getting-started/building.md)).
+
+## 1. The repository, from the phone's own device tree
+
+```sh
+adb pull /sys/firmware/fdt device-tree.dtb # the tree of the phone's own Android (or --adb below, which pulls it)
+tools/hakios-device.py new mydevice --soc sc7280 --title "My Phone" --vendor Someone --maintainer "you" --fdt device-tree.dtb
+make mydevice_defconfig
+make config
+```
+
+That makes `devices/mydevice/` with:
+
+- `soc.args`, `pull-soc.sh` and a README from `tools/new-device.py`: what the kernel needs to know about the SoC (`soc_*`: the
+ modem's blocks, the IPA, the mailboxes) read out of your phone's tree and compared with the reference phone. The same values
+ as the reference: the SoC code already fits. Differences go to the kernel through `soc.args`;
+- `device.conf`, a defconfig of three `#include` lines and a fragment in which **every phone driver of the common repository is
+ left out**: their addresses, pins and rails are the phone they were written for, and a driver of another phone touching yours
+ is the last thing you want. The drivers of your SoC (from its fragment) and QEMU's stay in.
+
+A SoC without a repository yet: make `socs/<soc>/` the same way by hand (`soc.conf`, `configs/<soc>.config`), from
+[socs/sc7280](https://github.com/shimoku74/hakios/tree/main/socs/sc7280).
+
+**Done when** `tools/hakios-device.py check mydevice` says it holds together, and the README says which SoC values differ and you
+know why.
+
+## 2. The first boot, with nothing of the phone's
+
+```sh
+make kernel # the kernel with only what the fragment kept
+make loader
+make phone SECS=120 # or ./xl enter, ./xl ramdisk, ./xl run, one at a time
+```
+
+What to look for in `logs/`: the loader's banner, `kernel.ver=`, the kernel's first lines, `hakios-kernel: N drivers built in (...)`
+with only the drivers you meant, and launchd. The display shows UEFI's framebuffer.
+
+**Done when** a run reaches launchd and ends by itself, and the phone comes back.
+
+## 3. The drivers, one at a time
+
+Bring them back in the order each needs the ones before it:
+
+| Order | Driver | Why then |
+|---|---|---|
+| 1 | `CPUFREQ`, `THERMAL`, `SOCINFO` | the SoC's: they read what the chip is and how warm, and touch nothing that is the phone's |
+| 2 | `BUTTONS`, then the touch screen (`GOODIX` or one of your own) | input, so that the system can be used |
+| 3 | `UFS` | the phone's storage, read only; the modem needs it |
+| 4 | `ADRENO` | the GPU; needs `fw-gpu/` |
+| 5 | `ADSP`, `BATTERY`, `SPEAKER`, `SOUND`, `MIC` | audio and the battery's level come through the audio DSP |
+| 6 | `WIFI` (and `QMI`) | needs `fw-wifi/` |
+| 7 | `HAPTIC`, `CAMERA`, `TORCH`, `MODEM`, `BT` | the rest |
+
+For each: read the head of the driver (`drivers/<subsystem>/hakios.<name>.c` says where every address and number came from), find
+the same in your phone's device tree, and change what differs. A value that is a SoC fact goes to the SoC's fragment or the
+kernel's defaults; a value that is the phone's goes into a boot-argument of the device's fragment where the driver reads one, or
+into a driver of the device's own when the hardware is another chip altogether ([Writing a driver](drivers.md)). Then
+`CONFIG_HAKIOS_<NAME>=y` in `configs/mydevice.config`, and the driver's boot-argument.
+
+**Done when** the part works on the phone: write it down as a `status` line in `device.conf`, with how it is turned on.
+
+## 4. Write it down
+
+```sh
+python3 tools/docs-gen.py # the device's page, from device.conf
+tools/hakios-device.py check mydevice
+```
+
+`device.conf` is the record of what works. Only what you have seen on the phone is `works`; what is written and not yet seen is
+`partial` with a note; what is not there is `missing`.
+
+## 5. Publish it
+
+[Publishing a device](repositories.md#publishing-a-device): split it into a repository of its own and add it to
+`devices/manifest.conf` in a pull request.
+
+## When a step does not work
+
+| Symptom | Look at |
+|---|---|
+| nothing after the loader's banner | the UEFI port: the loader needs the framebuffer and its file from UEFI |
+| the kernel stops early | the SoC's addresses (step 1); `soc.args` |
+| a driver's step fails | its log lines name the step and the register; the head of the driver says what each step needs |
+| `make config` reports a problem | it names the symbol and why: a driver left out that an argument needs, firmware the open profile does not load |
diff --git a/docs/porting/repositories.md b/docs/porting/repositories.md
new file mode 100644
index 0000000..3e1342c
--- /dev/null
+++ b/docs/porting/repositories.md
@@ -0,0 +1,116 @@
+# How the repositories fit
+
+HakiOS is put together from layers, the way an Android device's source is (`device/<vendor>/<name>`, a `<soc>-common`, a manifest
+that names them):
+
+```
+hakios/ common: the kernel port, every common driver, the loader, user space, the tools, the docs
+├── socs/<soc>/ a SoC family: soc.conf, configs/<soc>.config, drivers/ of its own
+├── devices/<name>/ a device: device.conf, configs/<name>_defconfig and <name>.config, drivers/, its UEFI, scripts
+└── devices/manifest.conf every SoC and device repository: kept in this tree, or a repository of its own at a revision
+```
+
+A SoC or device directory is the same whether it is kept in this tree or is a git repository of its own cloned into place: the
+tools look for `socs/*/soc.conf` and `devices/*/device.conf`, whatever put them there.
+
+## A device repository
+
+| File | What | Required |
+|---|---|---|
+| `device.conf` | what the device is, and how far each part works | yes |
+| `configs/<name>_defconfig` | `#include common_defconfig`, `#include <soc>.config`, `#include <name>.config` | yes |
+| `configs/<name>.config` | what is this device's own: drivers left out or in, arguments, `CONFIG_DEVICE="<name>"` | yes |
+| `drivers/<subsystem>/conf` and the files it names | drivers of its own ([Writing a driver](drivers.md)) | no |
+| `pull-firmware.sh` | the device's firmware, from your own device, into `fw-*/` | for a phone |
+| `uefi/`, `prebuilt/` | the device's UEFI port and the images made of it | for a phone |
+| `README.md` | anything else a person needs to know | yes |
+
+### `device.conf`
+
+```
+device redwood
+ title POCO X5 Pro 5G
+ vendor Xiaomi
+ soc sc7280
+ defconfig redwood_defconfig
+ firmware pull-firmware.sh
+ maintainer the HakiOS developers (README.md)
+ status touch works Goodix GT9916 / FocalTech FT3680 on SPI, multitouch (touchscreen=1)
+ status cellular partial the modem boots, sees the network; no registration yet
+ status bluetooth missing step one only
+```
+
+| Word | Means |
+|---|---|
+| `title`, `vendor` | what it is called |
+| `soc` | the SoC family: `socs/<soc>/` must be there; `none` for a machine without one (QEMU) |
+| `defconfig` | its defconfig, in its `configs/` |
+| `firmware` | the script that pulls its firmware |
+| `maintainer` | who answers for it |
+| `status <area> works\|partial\|missing <note>` | how far a part works, **as seen on this device**; the note says how it is turned on and what is not done. Areas: display, touch, buttons, cpu, gpu, storage, audio, battery, haptic, camera, torch, wifi, bluetooth, cellular, network, thermal, usb, sensors |
+
+The device's page in this documentation ([redwood](../devices/redwood.md)) and the table of [all devices](../devices/index.md)
+are made from it by `tools/docs-gen.py`: the status is written once, next to the code it describes.
+
+## A SoC repository
+
+```
+soc sc7280
+ title Qualcomm SC7280 family (SM7325 "Snapdragon 778G", QCM6490; "yupik", "kodiak")
+ vendor Qualcomm
+ cores 8, the biggest is core 7
+ gpu Adreno 642L
+ maintainer the HakiOS developers (README.md)
+```
+
+and `configs/<soc>.config`, the SoC's facts: `CONFIG_SOC`, its cores, and **the drivers of the SoC family**
+(`CONFIG_HAKIOS_CPUFREQ=y`, `CONFIG_HAKIOS_THERMAL=y`, ...), so that every device with the SoC has them, whatever it leaves out of
+its own.
+
+## The manifest
+
+`devices/manifest.conf` names every SoC and device:
+
+```
+soc sc7280
+ path socs/sc7280 kept in this tree
+
+device sheng
+ repository https://github.com/<you>/hakios-device-sheng.git
+ revision 0123456789abcdef0123456789abcdef01234567
+```
+
+| Command | Does |
+|---|---|
+| `tools/hakios-device.py list` (`make devices`) | every device and SoC, where it is, how much of it works |
+| `tools/hakios-device.py check [NAME...]` | a repository holds together: its conf reads, its defconfig includes the common kernel and its SoC's fragment and passes `hakios-config.py check`, its drivers' files are there, no two repositories have a configuration of the same name |
+| `tools/hakios-device.py new NAME --soc SOC --title ...` | a new device repository ([Port a device](index.md)) |
+| `tools/hakios-device.py sync [NAME...]` | clone or update the repositories that live elsewhere, at their revisions |
+| `tools/hakios-device.py lock NAME` | write the revision checked out into the manifest |
+| `tools/hakios-device.py split NAME DIR` | a device kept in this tree, as a git repository of its own with its history, ready to push |
+
+## How a device's own driver reaches the kernel
+
+A driver in `devices/<name>/drivers/<subsystem>/conf` is a `CONFIG_HAKIOS_<NAME>` symbol like the common ones. `make kernel` copies
+its files into the kernel tree (`xnu/sync-drivers.sh`, through `tools/hakios-config.py external-files`) and writes it into XNU's
+`conf/files` as `optional`; `xnu/export.sh` leaves it out of the common patch, because it is the device's. A device repository
+cannot declare `standard` files: what every kernel has is the common repository's to decide.
+
+## Publishing a device
+
+1. `tools/hakios-device.py check NAME` passes.
+2. `tools/hakios-device.py split NAME ../hakios-device-NAME` makes it a repository of its own.
+3. Push it to a repository named `hakios-device-NAME` (or `hakios-soc-SOC` for a SoC).
+4. In a pull request to the common repository: its block in `devices/manifest.conf` with `repository` and `revision`
+ (`tools/hakios-device.py lock NAME` writes it), and nothing else.
+
+## Compared with others
+
+| | Android | UniXNU | HakiOS |
+|---|---|---|---|
+| the shared part | AOSP, the GKI kernel | `UniXNU` (tools, components, ARM64 support) | `hakios` (the kernel port, drivers, loader, tools) |
+| a SoC | `<soc>-common` | `UniXNU-<soc>-common` (`soc.toml`) | `socs/<soc>` (`soc.conf`) |
+| a device | `device/<vendor>/<name>` | `UniXNU-<name>` (`board.toml`) | `devices/<name>` (`device.conf`) |
+| what names them | `repo` manifest | `devices.toml` | `devices/manifest.conf` |
+| a driver | kernel module, `Kconfig` | a component repository | `drivers/<sub>/conf`, an XNU `option` |
+| the status of a device | nothing of the kind | a page per device | `status` lines in `device.conf`, the page made from them, checked in CI |
diff --git a/docs/reference/drivers.md b/docs/reference/drivers.md
new file mode 100644
index 0000000..b0771c7
--- /dev/null
+++ b/docs/reference/drivers.md
@@ -0,0 +1,108 @@
+<!-- Made by tools/docs-gen.py from drivers/*/conf and the SoC and device repositories' drivers. Do not edit: change that, then run tools/docs-gen.py. -->
+
+
+# Drivers
+
+Every driver the kernel can be built with. `CONFIG_HAKIOS_<NAME>=y` in a defconfig builds it in; [Drivers in the configuration](../drivers-config.md) says how, and [Writing a driver](../porting/drivers.md) how to add one.
+
+## Always built
+
+| File | What |
+|---|---|
+| `hakios.audio.c` | /dev/hakios-audio, the sound iOS plays, to whatever plays it; and where the camera, flashlight, motor and speaker drivers are started from |
+| `hakios.version.c` | kern.hakios.version, and the version in the boot log |
+| `hakios.platform.c` | what the drivers share (the locks of the PMIC arbiter, the always-on processor, RPMh and the SMMU), and kern.hakios.drivers, the list of the drivers built in |
+| `hakios.stubs.c` | what the rest of the kernel calls in a driver that is left out: nothing, and "not there" |
+| `hakios.stubs.cpp` | the same, for the calls that are C++ (the display asking whether the GPU is done with a surface) (with XNU's `iokitcpp`) |
+| `hakios.input.c` | /dev/hakios-touch, the queue of touches and buttons, and where the phone's drivers are started from |
+| `hakios.net.c` | en0, an interface that is Ethernet to the rest of the kernel, for whatever link carries its frames |
+| `hakios.image.c` | a file of one of the RAM disks by path, for the drivers that load firmware before there is a root |
+| `hakios.sparse.c` | /dev/rsp0, a block device over an image that holds only some of its blocks (apfs_sparse=) |
+| `hakios.apfs_check.c` | a walk of the APFS volume on /dev/rvblk0 through VFS, to compare with tools/apfs/apfs.py (with XNU's `apfs`) |
+
+## audio
+
+| Driver | Files | Requires | Boot arguments | qemu | redwood | |
+|---|---|---|---|---|---|
+| **`HAKIOS_ADSP`**<br>the audio DSP started and linked (adsp=1, adsp_step=N); the battery's state comes through it too. Needs the DSP's firmware from the phone (fw-audio/) | `hakios.adsp.c` | | `adsp=`, `adsp_again=`, `adsp_apr_wait=`, `adsp_keep=`, `adsp_listen=`, `adsp_new=`, `adsp_pause=`, `adsp_return=` and 3 more | | built | |
+| **`HAKIOS_SPEAKER`**<br>the two speaker amplifiers on I2C, and their watch of temperature and battery | `hakios.speaker.c` | | `speaker_probe=` | | built | |
+| **`HAKIOS_SOUND`**<br>the speakers playing (sound=N): what the DSP's services are told, the feeder, and the speakers' guard that limits what the amplifiers get | `hakios.sound.c`<br>`hakios.guard.c` | `HAKIOS_ADSP`, `HAKIOS_SPEAKER` | `sound=`, `sound_below=`, `sound_gain=`, `sound_guard_as=`, `sound_pause=`, `sound_secs=` | | built | |
+| **`HAKIOS_MIC`**<br>the microphones, through the audio DSP (mic=N) | `hakios.mic.c` | `HAKIOS_ADSP`, `HAKIOS_SOUND` | `mic=`, `mic_adc=`, `mic_input=`, `mic_main=`, `mic_secs=`, `mic_tap=`, `mic_test=` | | built | |
+| **`HAKIOS_VIRTIO_SOUND`**<br>QEMU's virtio sound device as the player of /dev/hakios-audio (virtio_sound=1). QEMU only | `hakios.virtio_sound.c` | | `virtio_sound=` | built | built | |
+
+## bluetooth
+
+| Driver | Files | Requires | Boot arguments | qemu | redwood | |
+|---|---|---|---|---|---|
+| **`HAKIOS_BT`**<br>the Bluetooth half of the WCN6750: step one, a read-only look at its three pins (bt=1) | `hakios.bt.c` | | `bt=`, `bt_again=` | | built | |
+
+## camera
+
+| Driver | Files | Requires | Boot arguments | qemu | redwood | |
+|---|---|---|---|---|---|
+| **`HAKIOS_CAMERA`**<br>the cameras (cam=N): the sensors on the CCI bus and the ISP's interface. The sensors, their tables (fw-camera/) and the pins are the POCO X5 Pro's | `hakios.camera.c` | | `cam_after=`, `cam_fake=`, `cam_fake_fps=`, `cam_frames=`, `cam_gain=`, `cam_keep_mb=`, `cam_mode=`, `cam_pattern=` and 4 more | | built | |
+| **`HAKIOS_TORCH`**<br>the flashlight: the flash LED module of the PM8350C (torch=1); it stays off while the battery is too warm | `hakios.torch.c` | | `torch_max_s=`, `torch_secs=` | | built | |
+
+## core
+
+| Driver | Files | Requires | Boot arguments | qemu | redwood | |
+|---|---|---|---|---|---|
+| **`HAKIOS_SOCINFO`**<br>the chip's identity from the firmware's shared memory: kern.hakios.soc_* (socinfo=1). Any Qualcomm SoC that keeps SMEM item 137; where the shared memory is comes from soc_smem= | `hakios.socinfo.c` | | `soc_smem=`, `soc_smem_size=`, `socinfo=` | | built | |
+
+## gpu
+
+| Driver | Files | Requires | Boot arguments | qemu | redwood | |
+|---|---|---|---|---|---|
+| **`HAKIOS_ADRENO`**<br>the Adreno 642L of the SC7280 woken step by step (adreno=N), and HakiosGPU, the IOKit service Mesa and the window server draw through (gpu=1, adreno_keep=1). Needs the GPU's firmware from the phone (fw-gpu/) | `hakios.adreno.c`<br>`hakios.gpu.cpp` | | `adreno=`, `adreno_blind=`, `adreno_dirty=`, `adreno_fine=`, `adreno_keep=`, `adreno_only=`, `adreno_pause=`, `adreno_return=` and 10 more | | built | |
+
+## haptic
+
+| Driver | Files | Requires | Boot arguments | qemu | redwood | |
+|---|---|---|---|---|---|
+| **`HAKIOS_HAPTIC`**<br>the vibration motor: an Awinic AW86927 driving a linear resonant actuator (haptic=N), its waveforms from fw-haptic/ | `hakios.haptic.c` | | `haptic=`, `haptic_effect=` | | built | |
+
+## input
+
+| Driver | Files | Requires | Boot arguments | qemu | redwood | |
+|---|---|---|---|---|---|
+| **`HAKIOS_VIRTIO_INPUT`**<br>QEMU's virtio tablet and keyboard as the touch screen and the buttons (virtio_input=1). QEMU only | `hakios.virtio_input.c` | | `virtio_input=` | built | built | |
+| **`HAKIOS_GOODIX`**<br>the touch screen: a Goodix GT9916 ("Berlin-D") or a FocalTech FT3680 on SPI (touchscreen=1). The bus, pins and supplies are the POCO X5 Pro's; another phone with one of these controllers changes those | `hakios.goodix.c` | | `touch_flip=`, `touch_poll_us=`, `touch_rate=`, `touch_spi_hz=`, `touchscreen=` | | built | |
+| **`HAKIOS_BUTTONS`**<br>the power and volume keys, read from the PMIC through the SPMI arbiter (buttons=1) | `hakios.buttons.c` | | `buttons=`, `buttons_steps=`, `touchscreen=` | | built | |
+
+## modem
+
+| Driver | Files | Requires | Boot arguments | qemu | redwood | |
+|---|---|---|---|---|---|
+| **`HAKIOS_QMI`**<br>QMI messages over the IPC router: how the Wi-Fi firmware's service and the modem's are spoken to | `hakios.qmi.c` | | | | built | |
+| **`HAKIOS_MODEM`**<br>the modem (modem=1): started, its file systems served from the flash, the IPA's data path as en1, the SIM and the network registration. Research; needs fw-modem/ from the phone | `hakios.mpss.c`<br>`hakios.cell.c`<br>`hakios.nas.c`<br>`hakios.ipa.c` | `HAKIOS_QMI`, `HAKIOS_UFS` | `modem=`, `modem_again=`, `modem_apn=`, `modem_buffer=`, `modem_data_nobind=`, `modem_data_off=`, `modem_data_wait=`, `modem_dpm_off=` and 45 more | | built | |
+
+## net
+
+| Driver | Files | Requires | Boot arguments | qemu | redwood | |
+|---|---|---|---|---|---|
+| **`HAKIOS_VIRTIO_NET`**<br>QEMU's virtio network device as the link behind en0 (virtio_net=1). QEMU only | `hakios.virtio_net.c` | | `virtio_net=` | built | built | |
+
+## power
+
+| Driver | Files | Requires | Boot arguments | qemu | redwood | |
+|---|---|---|---|---|---|
+| **`HAKIOS_BATTERY`**<br>the battery: kern.hakios.battery_*, and HakiosBattery, the IOPMPowerSource iOS reads the charge from (the state comes from the audio DSP's battery manager, with adsp=1) | `hakios.battery.c`<br>`hakios.battery.cpp` | | `battery_shared_pa=` | | built | |
+| **`HAKIOS_CPUFREQ`**<br>the clock of the cores the kernel runs on (cpufreq=1), and the memory bus's votes (ddr=) | `hakios.cpufreq.c` | | `cpufreq=`, `cpuload=`, `ddr=`, `ddr_rest=`, `ddr_vote=`, `membench=` | | built | |
+| **`HAKIOS_THERMAL`**<br>the SoC's temperature sensors (thermal=1): kern.hakios.thermal_*, and the run handed back to the loader when the phone gets too hot (thermal_stop=) | `hakios.thermal.c` | | `thermal=`, `thermal_log=`, `thermal_poll=`, `thermal_stop=`, `thermal_tm0=`, `thermal_tm1=` | | built | |
+| **`HAKIOS_PMIC`**<br>the blocks of the power-management chips the SPMI arbiter shows, and the PMIC's clock (pmic=1); read only | `hakios.pmic.c` | | `pmic=`, `pmic_list=` | | built | |
+| **`HAKIOS_BATTGUARD`**<br>the run handed back to the loader before the battery is flat (battery_stop=<percent>) | `hakios.battguard.c` | | `battery_stop=`, `battery_stop_poll=` | | built | |
+
+## storage
+
+| Driver | Files | Requires | Boot arguments | qemu | redwood | |
+|---|---|---|---|---|---|
+| **`HAKIOS_UFS`**<br>the phone's UFS flash: a block device for each GPT partition (ufs=1, ufs=2), and the UFS host controller driven from the kernel (ufs_native=). THE ONLY CODE OF THE KERNEL THAT MAY WRITE TO THE PHONE (ufs_write=1, the partition `darwin` only): see tools/provenance.allow | `hakios.ufs.c`<br>`hakios.ufshc.c` | | `ufs_bench=`, `ufs_check=`, `ufs_native_bench=`, `ufs_native_buffer=`, `ufs_native_check=`, `ufs_native_hang=`, `ufs_native_leave=`, `ufs_native_slots=` and 3 more | | built | |
+| **`HAKIOS_VIRTIO_BLK`**<br>a disk image of the host as /dev/rvblk0 (virtio_blk=1). QEMU only | `hakios.virtio_blk.c` | | `virtio_blk=` | built | built | |
+
+## wifi
+
+| Driver | Files | Requires | Boot arguments | qemu | redwood | |
+|---|---|---|---|---|---|
+| **`HAKIOS_WIFI`**<br>Wi-Fi of the WCN6750 (wifi=1, wifi_step=N): the DSP that runs the radio's firmware, Linux's ath11k (its object, made by tools/mk-ath11k.sh, is linked in only with this), a station, and the Apple80211 surface iOS's wifid talks to. Needs fw-wifi/ from the phone | `hakios.wifi.c`<br>`hakios.wlfw.c`<br>`hakios.lx.c`<br>`hakios.sta.c`<br>`hakios.apple80211.c`<br>`hakios.wlan.cpp` | `HAKIOS_QMI` | `wifi=`, `wifi_again=`, `wifi_ask=`, `wifi_cal=`, `wifi_dirty=`, `wifi_file=`, `wifi_fine=`, `wifi_keep=` and 14 more | | built | |
+
+The columns on the right are the devices' defconfigs: "built" means that defconfig builds the driver in.
diff --git a/docs/reference/tools.md b/docs/reference/tools.md
new file mode 100644
index 0000000..102da0a
--- /dev/null
+++ b/docs/reference/tools.md
@@ -0,0 +1,51 @@
+# Commands
+
+Every `make` target is a script below it; run the script itself for its options (`--help`, or the comment at its top).
+
+## make
+
+| Target | Does |
+|---|---|
+| `make` | the list below |
+| `make doctor` | checks this machine (and a phone on `adb`) for what HakiOS needs |
+| `make fetch` | the OS files from the iOS 16.5 IPSW into `sysimage/` |
+| `make images` | `userland/root.apfs` and `userland/system.apfs` |
+| `make kernel` | the kernel from source, with the `.config`'s drivers |
+| `make loader` / `make loader-open` | the boot loader with your IPSW's identity / the placeholder that boots the open kernel only |
+| `make qemu` / `make qemu-open` | a session in QEMU with iOS / the open kernel with nothing of Apple's |
+| `make phone` | a session on the phone with the `.config`'s arguments |
+| `make firmware` | the phone's firmware off the phone (`devices/$(DEVICE)/pull-firmware.sh`) |
+| `make esp` | an EFI system partition tree for a UEFI-native boot ([UEFI boot](../uefi-boot.md)) |
+| `make prebuilt` | refresh `prebuilt/` from what was built |
+| `make clean` | the build output of the kernel, loader and images |
+| `make NAME_defconfig` | `.config` from a defconfig of any repository (`FRAGMENTS="open trace"` on top) |
+| `make NAME.config` | a fragment over the `.config` |
+| `make config` / `make savedefconfig` | what the `.config` is / it as a minimal defconfig |
+| `make devices` | the device and SoC repositories |
+
+## tools/
+
+| Tool | Does | Page |
+|---|---|---|
+| `hakios-config.py` | defconfigs, fragments, `.config`, boot-arguments, the drivers' choice into the kernel tree | [Configuration](../configs.md) |
+| `hakios-device.py` | device and SoC repositories: list, check, new, sync, lock, split | [Repositories](../porting/repositories.md) |
+| `new-device.py` | a device's directory from the phone's own device tree: `soc.args`, how far the SoC code carries | [Port a device](../porting/index.md) |
+| `boot-args.py` | the catalogue of every boot-argument the source reads | [Boot arguments](../boot-args.md) |
+| `docs-gen.py` | the pages of this documentation made from the source | |
+| `drivers-check.py` | `drivers/map` and `drivers/*/conf` agree | [Drivers in the configuration](../drivers-config.md) |
+| `make-kernel.sh` | the kernel build `make kernel` runs, judged by what failed | [Building](../getting-started/building.md) |
+| `kernel-version.py` | the kernel's version string, `kernel.ver` | [Versioning](../versioning.md) |
+| `provenance-check.py` | nothing in the tree that must not be, and every piece of code that can write to a phone declared | |
+| `metallib.py` | a `.metallib` taken apart | [AIR](../air.md) |
+| `metallib-test.sh`, `metal-plugin-test.sh` | the Metal plug-in's reading of libraries and its objects, under sanitizers | [Metal plan](../metal-plan.md) |
+| `modem-cycle.sh` | a whole phone session in one command | [On the phone](../getting-started/phone.md) |
+| `soc-args.py` | the `soc_*` addresses out of a device tree | |
+| `backup-partitions.py` | a read-only backup of the phone's partitions, each copy proven | [Install, safely](../install-safe.md) |
+
+## xnu/
+
+| Script | Does |
+|---|---|
+| `xnu/apply.sh` | Apple's XNU at the tag, with `hakios.patch`, `files/`, the drivers and the drivers' choice laid over it, into `xnu-src/` |
+| `xnu/sync-drivers.sh` | the drivers edited in `drivers/` (and the SoC's and device's) into the tree |
+| `xnu/export.sh` | the tree back into `hakios.patch`, `files/` and `drivers/` |
diff --git a/docs/ru/notes.md b/docs/ru/notes.md
index 0ffc11e..c0fac64 100644
--- a/docs/ru/notes.md
+++ b/docs/ru/notes.md
@@ -115,7 +115,7 @@ AUDIO=pipewire qemu/run-ios.sh 1200 -display gtk > logs/qemu.log # или AUD
сеанса `./xl sound out.wav` достаёт их (в QEMU — `pmemsave` по адресу из строки `hakios-audio: recording … at 0x…`,
затем `tools/sound.py`); с `rec_sound_fed=1` — то, что ушло к усилителям. На телефоне звук проверен на слух.
Защиты динамиков, которая у Android работает в звуковом процессоре (алгоритм Awinic с калибровкой), здесь нет;
-вместо неё отсчёты по пути к усилителям проходят «сторож» ядра (`drivers/storage/hakios.guard.c`): сначала усиление
+вместо неё отсчёты по пути к усилителям проходят «сторож» ядра (`drivers/audio/hakios.guard.c`): сначала усиление
`sound_gain` (по умолчанию и самое большее 12 дБ: обработка самой iOS для динамика iPhone X держит даже полный тон
на максимуме громкости на 12,6–14,3 дБ ниже полной шкалы), затем фильтр верхних частот 200 Гц, три средних мощности
на динамике — за 0,2, 3 и 60 с, пределы на 3, 6 и 9 дБ ниже мощности синуса полной шкалы на уровне Android (громкость
@@ -2262,7 +2262,7 @@ SpringBoard спрашивает десять тысяч раз за все се
каждые 15 секунд, того не стоит. Заглушить первый драйвер — работа того же рода, что `HakiosBattery`; второй —
это модем Apple на PCIe, а модем этого телефона сидит на самом кристалле и говорит по QMI с подсистемой
Qualcomm, так что за драйвером нет и того, к чему он ведёт.
-Текущий план подключения MPSS и проверка аппаратных ресурсов: [docs/cellular.md](docs/cellular.md).
+Текущий план подключения MPSS и проверка аппаратных ресурсов: [docs/cellular.md](../cellular.md).
**Остальные из того же списка «никогда не пробовали».** `cloudd` и `mobileassetd` не падают, и 42 ненайденных
обращения за сеанс с ними исчезают (`com.apple.cloudd` — 26, `com.apple.mobileassetd.v2` — 16). И всё-таки
@@ -2317,7 +2317,7 @@ Mesa в репозитории нет: `tools/mk-mesa.sh` один раз ска
### UEFI для телефона
-См. `devices/redwood/uefi/README.md` (порт Project Silicium на redwood). Для запуска пересобирать не нужно: `mkxnuimg.py` берёт
+См. `uefi/README.md` (порт Project Silicium на redwood). Для запуска пересобирать не нужно: `mkxnuimg.py` берёт
готовое из `devices/redwood/prebuilt`.
## Как это устроено
diff --git a/docs/uefi-boot.md b/docs/uefi-boot.md
index 34d422b..6f137df 100644
--- a/docs/uefi-boot.md
+++ b/docs/uefi-boot.md
@@ -56,7 +56,7 @@ A file that is not a payload gives `is not a payload (no XNUP at its start)`, an
## 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/redwood/uefi/README.md`). It does not look for a loader on a
+ leaves in memory instead of a menu** (`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.
diff --git a/docs/versioning.md b/docs/versioning.md
index d03e454..df6c106 100644
--- a/docs/versioning.md
+++ b/docs/versioning.md
@@ -16,7 +16,7 @@ commit. This kernel says the same kind of thing about itself:
## Where it is shown
-1. **The loader's banner** (`xnuloader/`), under `HAKIOS`: `hello hackios-kernel!` and `kernel.ver=<the string>`.
+1. **The loader's banner** (`xnuloader/`), under `HAKIOS`: `hello hakios-kernel!` and `kernel.ver=<the string>`.
2. **The kernel**: a line in the boot log, and `sysctl kern.hakios.version` (`userland/src/hello.c` prints it).
3. **The payload**: `xnuloader/mkpayload.py` puts it in as the entry `kernel.ver`; the loader hands it to the kernel on
its command line as `hakios_kver=`. A kernel started some other way (no loader) says `unknown`: it does not guess.
diff --git a/docs/windows.md b/docs/windows.md
index c44dabe..31234b7 100644
--- a/docs/windows.md
+++ b/docs/windows.md
@@ -43,7 +43,7 @@ from Git Bash.
# WSL, in ~/hakios (a clone in WSL's own filesystem, with fw-*/ copied in):
sysimage/fetch.sh # iOS 16.5 from Apple's servers, ~9 min
PREBUILT=1 REST=1 MODEM=1 SYSTEM=1 userland/build.sh # root.apfs + system.apfs, ~4 min, no theos needed
-cp userland/root.apfs userland/system.apfs /mnt/d/.../hackios-xnu-kernel/userland/
+cp userland/root.apfs userland/system.apfs /mnt/d/.../hakios/userland/
# Git Bash, in the Windows checkout:
./xl enter # Android -> fastboot -> the loader in RAM (also the unlock test)
diff --git a/drivers/README.md b/drivers/README.md
index c968257..db92408 100644
--- a/drivers/README.md
+++ b/drivers/README.md
@@ -6,12 +6,15 @@ The kernel's own drivers, by subsystem, the way Linux keeps `drivers/`. They are
| Where | Is |
|---|---|
| `drivers/map` | the list: for each file, its subsystem and the path it has in Apple's tree |
+| `drivers/<subsystem>/conf` | which drivers there are and which files each one is: `CONFIG_HAKIOS_<NAME>` in a defconfig builds it in ([docs/drivers-config.md](../docs/drivers-config.md)) |
| `xnu/apply.sh` | lays Apple's tag, `xnu/hakios.patch`, `xnu/files/` and these drivers into one tree |
| `xnu/export.sh` | the reverse, run before committing; refuses a new `hakios.*` file that `drivers/map` does not list |
| `tools/drivers-check.py` | CI: the map and the directories agree, nothing is listed twice, nothing is kept in two places |
-Adding a driver: put it in `drivers/<subsystem>/`, add a line to `drivers/map`, add its `bsd/conf/files` line to
-the patch (as the others have), `python3 tools/drivers-check.py`. A driver that is started by a boot argument
+Adding a driver: put it in `drivers/<subsystem>/`, add a line to `drivers/map`, a `driver` block (or a `standard` line) to
+`drivers/<subsystem>/conf`, `python3 tools/drivers-check.py`. The `bsd/conf/files` and `iokit/conf/files` lines are made from
+the conf files (`tools/hakios-config.py kernel`); if the rest of the kernel calls the driver, a stand-in for when it is left out
+goes into `core/hakios.stubs.c`. A driver that is started by a boot argument
has to be in `docs/boot-args.md` (`python3 tools/boot-args.py --check`).
## Subsystems
@@ -19,17 +22,17 @@ has to be in `docs/boot-args.md` (`python3 tools/boot-args.py --check`).
| Directory | Drivers | Boot arguments | What it is |
|---|---|---|---|
| `input/` | `hakios.goodix.c`, `hakios.input.c`, `hakios.buttons.c`, `hakios.virtio_input.c` | `touchscreen=` | the touch controller, the event queue behind `/dev/hakios-touch`, the buttons, QEMU's virtio input |
-| `storage/` | `hakios.ufs.c`, `hakios.ufshc.c/.h`, `hakios.sparse.c`, `hakios.image.c`, `hakios.guard.c`, `hakios.apfs_check.c`, `hakios.virtio_blk.c` | `ufs=`, `ufs_write=`, `ufs_native=` | the phone's flash (UFS), the sparse and image devices, the checks of the APFS read path, QEMU's virtio-blk. **The only code of the kernel that may write to the phone**: see `tools/provenance.allow` |
+| `storage/` | `hakios.ufs.c`, `hakios.ufshc.c/.h`, `hakios.sparse.c`, `hakios.image.c`, `hakios.apfs_check.c`, `hakios.virtio_blk.c` | `ufs=`, `ufs_write=`, `ufs_native=` | the phone's flash (UFS), the sparse and image devices, the checks of the APFS read path, QEMU's virtio-blk. **The only code of the kernel that may write to the phone**: see `tools/provenance.allow` |
| `gpu/` | `hakios.adreno.c`, `hakios.gpu.cpp` | `gpu=`, `adreno=` | the Adreno GPU bring-up and the IOKit object user space talks to |
| `camera/` | `hakios.camera.c`, `hakios.torch.c` | `cam=`, `torch=` | the camera sensors and ISP interface, the flashlight LED |
| `haptic/` | `hakios.haptic.c` | `haptic=` | the vibration motor |
-| `audio/` | `hakios.adsp.c`, `hakios.audio.c`, `hakios.sound.c`, `hakios.speaker.c`, `hakios.mic.c`, `hakios.virtio_sound.c` | `adsp=`, `sound=`, `mic=` | the audio DSP loader, `/dev/hakios-audio`, the speaker amplifiers and their guard, the microphone, QEMU's virtio sound |
+| `audio/` | `hakios.adsp.c`, `hakios.audio.c`, `hakios.sound.c`, `hakios.guard.c`, `hakios.speaker.c`, `hakios.mic.c`, `hakios.virtio_sound.c` | `adsp=`, `sound=`, `mic=` | the audio DSP loader, `/dev/hakios-audio`, the speaker amplifiers and their guard (`hakios.guard.c`, until now in `storage/`), the microphone, QEMU's virtio sound |
| `power/` | `hakios.battery.c/.cpp`, `hakios.cpufreq.c`, `hakios.thermal.c`, `hakios.pmic.c`, `hakios.battguard.c` | `cpufreq=`, `battmgr=`, `thermal=`, `pmic=`, `battery_stop=` | battery readings (through the DSP), CPU frequency, temperature limits that hand control back to the loader, the PMIC, and an end to an unwatched run before the battery is flat (compiled only: see its head for what it was checked against) |
| `wifi/` | `hakios.wifi.c`, `hakios.wlfw.c`, `hakios.lx.c`, `hakios.sta.c`, `hakios.apple80211.c`, `hakios.wlan.cpp` | `wifi=`, `wifi_step=` | the Wi-Fi subsystem's bring-up, the WLAN firmware service, the Linux-driver layer (`wifi/lx/`) and the surface the iOS Wi-Fi service expects |
| `bluetooth/` | `hakios.bt.c` | `bt=` | Bluetooth of the WCN6750 radio chip: step one, a look at its three pins, read only (compiled only; the rest is written down in the file's head as what it needs) |
| `modem/` | `hakios.mpss.c`, `hakios.cell.c`, `hakios.qmi.c`, `hakios.nas.c`, `hakios.ipa.c` | `modem=` | the cellular modem path (research; not reviewed in `docs/driver-review/`) |
| `net/` | `hakios.net.c`, `hakios.virtio_net.c` | | the `enN` network interface and QEMU's virtio-net |
-| `core/` | `hakios.version.c`, `hakios.socinfo.c` | `hakios_kver=`, `socinfo=` | `kern.hakios.version`; the SoC's identity as the hardware reports it |
+| `core/` | `hakios.version.c`, `hakios.platform.c`, `hakios.stubs.c`, `hakios.socinfo.c` | `hakios_kver=`, `socinfo=` | `kern.hakios.version`; what the drivers share (the hardware locks several take turns at, the `kern.hakios` node, `kern.hakios.drivers`); what the kernel calls in a driver that is left out; the SoC's identity as the hardware reports it |
## Reviews
diff --git a/drivers/audio/conf b/drivers/audio/conf
new file mode 100644
index 0000000..a62e9eb
--- /dev/null
+++ b/drivers/audio/conf
@@ -0,0 +1,32 @@
+# drivers/audio/conf: the audio DSP, the speakers, the microphones, and /dev/hakios-audio.
+# CONFIG_HAKIOS_<NAME>=y in a defconfig builds a driver into the kernel; "standard" files are always built.
+# tools/hakios-config.py reads this file; docs/drivers-config.md says what each word means and how it reaches XNU.
+
+standard bsd/dev/hakios.audio.c
+ help /dev/hakios-audio, the sound iOS plays, to whatever plays it; and where the camera, flashlight, motor
+ help and speaker drivers are started from
+
+driver ADSP
+ file bsd/dev/hakios.adsp.c
+ help the audio DSP started and linked (adsp=1, adsp_step=N); the battery's state comes through it too.
+ help Needs the DSP's firmware from the phone (fw-audio/)
+
+driver SPEAKER
+ file bsd/dev/hakios.speaker.c
+ help the two speaker amplifiers on I2C, and their watch of temperature and battery
+
+driver SOUND
+ file bsd/dev/hakios.sound.c
+ file bsd/dev/hakios.guard.c
+ requires ADSP SPEAKER
+ help the speakers playing (sound=N): what the DSP's services are told, the feeder, and the speakers' guard
+ help that limits what the amplifiers get
+
+driver MIC
+ file bsd/dev/hakios.mic.c
+ requires ADSP SOUND
+ help the microphones, through the audio DSP (mic=N)
+
+driver VIRTIO_SOUND
+ file bsd/dev/hakios.virtio_sound.c
+ help QEMU's virtio sound device as the player of /dev/hakios-audio (virtio_sound=1). QEMU only
diff --git a/drivers/bluetooth/conf b/drivers/bluetooth/conf
new file mode 100644
index 0000000..3cec0bf
--- /dev/null
+++ b/drivers/bluetooth/conf
@@ -0,0 +1,7 @@
+# drivers/bluetooth/conf: Bluetooth.
+# CONFIG_HAKIOS_<NAME>=y in a defconfig builds a driver into the kernel; "standard" files are always built.
+# tools/hakios-config.py reads this file; docs/drivers-config.md says what each word means and how it reaches XNU.
+
+driver BT
+ file bsd/dev/hakios.bt.c
+ help the Bluetooth half of the WCN6750: step one, a read-only look at its three pins (bt=1)
diff --git a/drivers/camera/conf b/drivers/camera/conf
new file mode 100644
index 0000000..b87301c
--- /dev/null
+++ b/drivers/camera/conf
@@ -0,0 +1,12 @@
+# drivers/camera/conf: the cameras and the flashlight.
+# CONFIG_HAKIOS_<NAME>=y in a defconfig builds a driver into the kernel; "standard" files are always built.
+# tools/hakios-config.py reads this file; docs/drivers-config.md says what each word means and how it reaches XNU.
+
+driver CAMERA
+ file bsd/dev/hakios.camera.c
+ help the cameras (cam=N): the sensors on the CCI bus and the ISP's interface. The sensors, their tables
+ help (fw-camera/) and the pins are the POCO X5 Pro's
+
+driver TORCH
+ file bsd/dev/hakios.torch.c
+ help the flashlight: the flash LED module of the PM8350C (torch=1); it stays off while the battery is too warm
diff --git a/drivers/camera/hakios.camera.c b/drivers/camera/hakios.camera.c
index e258296..fb632f7 100644
--- a/drivers/camera/hakios.camera.c
+++ b/drivers/camera/hakios.camera.c
@@ -1107,7 +1107,7 @@ ctab_load(void)
{
const uint8_t *at, *end;
- ctab = (const struct ctab_head *)hakios_wifi_file(hw->tab, &ctab_size);
+ ctab = (const struct ctab_head *)hakios_image_file("fw", hw->tab, &ctab_size, NULL);
if (ctab == NULL || ctab_size < sizeof(*ctab) || memcmp(ctab->magic, "RWCTAB02", 8) != 0 || ctab->modes == 0 ||
ctab->modes > 16) {
say("camera: no %s (RWCTAB02) in fw/ of the small image (made from fw-camera/ when it is built)\n", hw->tab);
diff --git a/drivers/core/conf b/drivers/core/conf
new file mode 100644
index 0000000..eed49ea
--- /dev/null
+++ b/drivers/core/conf
@@ -0,0 +1,21 @@
+# drivers/core/conf: what is part of every kernel of this port, and the chip's identity.
+# CONFIG_HAKIOS_<NAME>=y in a defconfig builds a driver into the kernel; "standard" files are always built.
+# tools/hakios-config.py reads this file; docs/drivers-config.md says what each word means and how it reaches XNU.
+
+standard bsd/dev/hakios.version.c
+ help kern.hakios.version, and the version in the boot log
+
+standard bsd/dev/hakios.platform.c
+ help what the drivers share (the locks of the PMIC arbiter, the always-on processor, RPMh and the SMMU), and
+ help kern.hakios.drivers, the list of the drivers built in
+
+standard bsd/dev/hakios.stubs.c
+ help what the rest of the kernel calls in a driver that is left out: nothing, and "not there"
+
+standard iokit/Kernel/hakios.stubs.cpp iokitcpp
+ help the same, for the calls that are C++ (the display asking whether the GPU is done with a surface)
+
+driver SOCINFO
+ file bsd/dev/hakios.socinfo.c
+ help the chip's identity from the firmware's shared memory: kern.hakios.soc_* (socinfo=1). Any Qualcomm SoC
+ help that keeps SMEM item 137; where the shared memory is comes from soc_smem=
diff --git a/drivers/core/hakios.platform.c b/drivers/core/hakios.platform.c
new file mode 100644
index 0000000..85fd700
--- /dev/null
+++ b/drivers/core/hakios.platform.c
@@ -0,0 +1,67 @@
+/*
+ * What the drivers share, kept apart from any one of them, so that each can be left out of the kernel on its own
+ * (drivers/<subsystem>/conf, CONFIG_HAKIOS_*: docs/drivers-config.md).
+ *
+ * the locks of the hardware several drivers take turns at: the PMIC arbiter (the buttons, the flashlight, the
+ * camera's regulators, the PMIC survey), the always-on processor's mailbox, the shared memory's
+ * allocation and RPMh's sequencer (the Wi-Fi, audio DSP and modem bring-ups, the touch screen's
+ * supply), and the SMMU's free match registers (Wi-Fi, sound, camera, modem). They were in
+ * hakios.buttons.c and hakios.wifi.c, which the others then needed in the kernel to link.
+ * kern.hakios the sysctl node the drivers hang theirs under (it was hakios.battery.c's)
+ * the list of the drivers this kernel was built with: sysctl kern.hakios.drivers, and a line in the boot log,
+ * so that a run says what was in it (hakios.drivers.h is made by tools/hakios-config.py kernel).
+ */
+#include <kern/locks.h>
+#include <kern/startup.h>
+#include <libkern/libkern.h>
+#include <sys/sysctl.h>
+#include <sys/systm.h>
+
+#include "hakios.drivers.h"
+
+/* kern.hakios: the node every driver of this port hangs its sysctls under (it was hakios.battery.c's) */
+SYSCTL_NODE(_kern, OID_AUTO, hakios, CTLFLAG_RW | CTLFLAG_LOCKED, 0, "redwood phone bits");
+
+static LCK_GRP_DECLARE(hakios_platform_lock_group, "hakios-platform");
+
+/*
+ * One transfer at a time through the PMIC arbiter for this system, whoever asks: with two at once the arbiter drops
+ * one ("the transfer was dropped"), as Linux never lets happen (one lock for the bus). A spin lock: it is taken
+ * around a transfer of some tens of microseconds.
+ */
+static LCK_SPIN_DECLARE(spmi_lock, &hakios_platform_lock_group);
+
+void
+hakios_spmi_lock(void)
+{
+ lck_spin_lock(&spmi_lock);
+}
+
+void
+hakios_spmi_unlock(void)
+{
+ lck_spin_unlock(&spmi_lock);
+}
+
+/*
+ * What the DSPs' starts use while another may be at work beside them: the mailbox to the always-on processor, one
+ * message at a time, and the allocation of items in the shared memory (whose hardware lock both take under the same
+ * number, so it does not keep the two apart); RPMh's sequencer (TCS 0 of the RSC); a free match register and context
+ * of the SMMU, found and taken.
+ */
+LCK_MTX_DECLARE(hakios_aop_mailbox_lock, &hakios_platform_lock_group);
+LCK_MTX_DECLARE(hakios_smem_alloc_lock, &hakios_platform_lock_group);
+LCK_MTX_DECLARE(hakios_rsc_lock, &hakios_platform_lock_group);
+LCK_MTX_DECLARE(hakios_smmu_lock, &hakios_platform_lock_group);
+
+static char hakios_drivers_string[] = HAKIOS_DRIVERS_LIST;
+
+SYSCTL_STRING(_kern_hakios, OID_AUTO, drivers, CTLFLAG_RD | CTLFLAG_LOCKED, hakios_drivers_string, 0,
+ "the drivers this kernel was built with (CONFIG_HAKIOS_* of its configuration, lowercase)");
+
+static void
+hakios_platform_init(void)
+{
+ printf("hakios-kernel: %d drivers built in (%s): %s\n", HAKIOS_DRIVERS_COUNT, HAKIOS_DRIVERS_CONFIG, hakios_drivers_string);
+}
+STARTUP(EARLY_BOOT, STARTUP_RANK_LAST, hakios_platform_init);
diff --git a/drivers/core/hakios.stubs.c b/drivers/core/hakios.stubs.c
new file mode 100644
index 0000000..ed5ca7f
--- /dev/null
+++ b/drivers/core/hakios.stubs.c
@@ -0,0 +1,137 @@
+/*
+ * What the rest of the kernel calls in a driver that is left out of it (CONFIG_HAKIOS_<NAME> not set: drivers/<subsystem>/conf,
+ * docs/drivers-config.md), the way XNU keeps bsd/kern/bsd_stubs.c for its own parts that a configuration leaves out.
+ *
+ * The callers are the places that start the drivers (hakios.input.c, hakios.audio.c, bsd_init.c), that stop them on
+ * the way back to the loader or out of a panic (loader_return.c, the thermal and battery guards, machine_routines.c)
+ * and the few that ask a driver something on the way (is this device one of the storage's, what the battery's
+ * temperature is). Each of them calls the driver unconditionally, as it did when every driver was always built; here,
+ * for a driver that is not, is what each call then does: nothing, and the answer "no", "not known" or "not there".
+ * A driver that is built gets none of this: every block below is for one driver, and empty when that one is in.
+ *
+ * What is not here, on purpose: a call from one driver to another that it cannot work without. That is a `requires`
+ * of its conf (SOUND requires ADSP and SPEAKER, MODEM requires QMI and UFS, ...), and tools/hakios-config.py refuses
+ * the configuration that would need a stand-in for it.
+ */
+#include <stdbool.h>
+#include <stdint.h>
+#include <sys/errno.h>
+#include <sys/types.h>
+#include <sys/hakios.audio.h>
+#include <sys/hakios.input.h>
+#include <sys/hakios.net.h>
+#include <sys/hakios.virtio_blk.h>
+
+/* the ends of a run (loader_return.c, the guards), which have no header of their own */
+void hakios_adsp_stop(void);
+void hakios_adsp_quiesce(void);
+void hakios_mpss_stop(void);
+void hakios_mpss_quiesce(void);
+void hakios_ddr_quiesce(void);
+void hakios_ufs_quiesce(void);
+void hakios_var_save_on_return(void);
+void hakios_mic_quiesce(void);
+void HakiosWLANStart(const char *interface, const uint8_t *address);
+
+#ifndef HAKIOS_VIRTIO_INPUT
+void hakios_virtio_input_init(void) {}
+#endif
+
+#ifndef HAKIOS_GOODIX
+void hakios_goodix_init(void) {}
+#endif
+
+#ifndef HAKIOS_BUTTONS
+void hakios_buttons_init(void) {}
+#endif
+
+#ifndef HAKIOS_UFS
+void hakios_ufs_init(void) {}
+void hakios_ufs_report(__unused const char *when) {}
+bool hakios_ufs_dev(__unused dev_t dev) { return false; }
+void hakios_ufs_quiesce(void) {}
+void hakios_var_save_on_return(void) {} /* no flash, so no data volume to save into it */
+#endif
+
+#ifndef HAKIOS_VIRTIO_BLK
+void hakios_virtio_blk_init(void) {}
+bool hakios_virtio_blk_dev(__unused dev_t dev) { return false; }
+#endif
+
+#ifndef HAKIOS_BATTERY
+void hakios_battery_init(void) {}
+int hakios_battery_temperature(void) { return -273; } /* "not known", as the driver says before its first reading */
+void hakios_battery_report(__unused const struct hakios_battery_state *state) {}
+#endif
+
+#ifndef HAKIOS_CPUFREQ
+void hakios_cpufreq_init(void) {}
+void hakios_ddr_quiesce(void) {}
+#endif
+
+#ifndef HAKIOS_ADRENO
+void hakios_adreno_init(void) {}
+void hakios_adreno_quiesce(void) {}
+void hakios_adreno_stop(void) {}
+void hakios_adreno_minute(void) {}
+#endif
+
+#ifndef HAKIOS_WIFI
+void hakios_wifi_init(void) {}
+void hakios_wifi_stop(void) {}
+void hakios_wifi_quiesce(void) {}
+errno_t hakios_apple80211_ioctl(__unused u_long command, __unused void *data) { return EOPNOTSUPP; }
+void HakiosWLANStart(__unused const char *interface, __unused const uint8_t *address) {}
+#endif
+
+#ifndef HAKIOS_ADSP
+void hakios_adsp_init(void) {}
+void hakios_adsp_stop(void) {}
+void hakios_adsp_quiesce(void) {}
+#endif
+
+#ifndef HAKIOS_MODEM
+void hakios_mpss_init(void) {}
+void hakios_mpss_stop(void) {}
+void hakios_mpss_quiesce(void) {}
+#endif
+
+#ifndef HAKIOS_VIRTIO_NET
+void hakios_virtio_net_init(void) {}
+#endif
+
+#ifndef HAKIOS_VIRTIO_SOUND
+void hakios_virtio_sound_init(void) {}
+#endif
+
+#ifndef HAKIOS_SPEAKER
+void hakios_speaker_init(void) {}
+#endif
+
+#ifndef HAKIOS_SOUND
+void hakios_sound_dsp_up(void) {}
+void hakios_sound_dsp_down(void) {}
+void hakios_sound_quiesce(void) {}
+#endif
+
+#ifndef HAKIOS_MIC
+void hakios_mic_dsp_up(void) {}
+void hakios_mic_dsp_down(void) {}
+void hakios_mic_quiesce(void) {}
+#endif
+
+#ifndef HAKIOS_HAPTIC
+void hakios_haptic_init(void) {}
+void hakios_haptic_quiesce(void) {}
+void hakios_haptic_pretend(__unused uint32_t peak) {}
+#endif
+
+#ifndef HAKIOS_TORCH
+void hakios_torch_init(void) {}
+void hakios_torch_quiesce(void) {}
+#endif
+
+#ifndef HAKIOS_CAMERA
+void hakios_camera_init(void) {}
+void hakios_camera_quiesce(void) {}
+#endif
diff --git a/drivers/core/hakios.stubs.cpp b/drivers/core/hakios.stubs.cpp
new file mode 100644
index 0000000..be721ec
--- /dev/null
+++ b/drivers/core/hakios.stubs.cpp
@@ -0,0 +1,14 @@
+/*
+ * The IOKit half of drivers/core/hakios.stubs.c: what the rest of the kernel calls in a driver that is left out of it,
+ * for the calls that are C++ (docs/drivers-config.md).
+ */
+#include "MiniIOSurface.h"
+
+#ifndef HAKIOS_ADRENO
+/* the display's driver asks whether the GPU is done with a surface before it shows it: with no GPU nothing draws into one */
+bool
+MiniIOSurfaceDrawn(__unused MiniIOSurface * surface, __unused uint64_t milliseconds)
+{
+ return true;
+}
+#endif
diff --git a/drivers/gpu/conf b/drivers/gpu/conf
new file mode 100644
index 0000000..931c63a
--- /dev/null
+++ b/drivers/gpu/conf
@@ -0,0 +1,9 @@
+# drivers/gpu/conf: the GPU.
+# CONFIG_HAKIOS_<NAME>=y in a defconfig builds a driver into the kernel; "standard" files are always built.
+# tools/hakios-config.py reads this file; docs/drivers-config.md says what each word means and how it reaches XNU.
+
+driver ADRENO
+ file bsd/dev/hakios.adreno.c
+ file iokit/Kernel/hakios.gpu.cpp iokitcpp
+ help the Adreno 642L of the SC7280 woken step by step (adreno=N), and HakiosGPU, the IOKit service Mesa and
+ help the window server draw through (gpu=1, adreno_keep=1). Needs the GPU's firmware from the phone (fw-gpu/)
diff --git a/drivers/haptic/conf b/drivers/haptic/conf
new file mode 100644
index 0000000..b0012cf
--- /dev/null
+++ b/drivers/haptic/conf
@@ -0,0 +1,8 @@
+# drivers/haptic/conf: the vibration motor.
+# CONFIG_HAKIOS_<NAME>=y in a defconfig builds a driver into the kernel; "standard" files are always built.
+# tools/hakios-config.py reads this file; docs/drivers-config.md says what each word means and how it reaches XNU.
+
+driver HAPTIC
+ file bsd/dev/hakios.haptic.c
+ help the vibration motor: an Awinic AW86927 driving a linear resonant actuator (haptic=N), its waveforms
+ help from fw-haptic/
diff --git a/drivers/haptic/hakios.haptic.c b/drivers/haptic/hakios.haptic.c
index 8650ba5..f5e6205 100644
--- a/drivers/haptic/hakios.haptic.c
+++ b/drivers/haptic/hakios.haptic.c
@@ -563,7 +563,7 @@ static bool
load_waveforms(void)
{
uint64_t size = 0;
- const uint8_t *file = hakios_wifi_file("aw8697_haptic.bin", &size);
+ const uint8_t *file = hakios_image_file("fw", "aw8697_haptic.bin", &size, NULL);
uint32_t sum = 0, base, length;
uint8_t address[2], back[64];
diff --git a/drivers/input/conf b/drivers/input/conf
new file mode 100644
index 0000000..63d10a4
--- /dev/null
+++ b/drivers/input/conf
@@ -0,0 +1,19 @@
+# drivers/input/conf: touch, buttons, and the queue they post to.
+# CONFIG_HAKIOS_<NAME>=y in a defconfig builds a driver into the kernel; "standard" files are always built.
+# tools/hakios-config.py reads this file; docs/drivers-config.md says what each word means and how it reaches XNU.
+
+standard bsd/dev/hakios.input.c
+ help /dev/hakios-touch, the queue of touches and buttons, and where the phone's drivers are started from
+
+driver VIRTIO_INPUT
+ file bsd/dev/hakios.virtio_input.c
+ help QEMU's virtio tablet and keyboard as the touch screen and the buttons (virtio_input=1). QEMU only
+
+driver GOODIX
+ file bsd/dev/hakios.goodix.c
+ help the touch screen: a Goodix GT9916 ("Berlin-D") or a FocalTech FT3680 on SPI (touchscreen=1). The bus,
+ help pins and supplies are the POCO X5 Pro's; another phone with one of these controllers changes those
+
+driver BUTTONS
+ file bsd/dev/hakios.buttons.c
+ help the power and volume keys, read from the PMIC through the SPMI arbiter (buttons=1)
diff --git a/drivers/input/hakios.buttons.c b/drivers/input/hakios.buttons.c
index 93a7da2..3c9b01a 100644
--- a/drivers/input/hakios.buttons.c
+++ b/drivers/input/hakios.buttons.c
@@ -123,25 +123,7 @@ wr(vm_offset_t address, uint32_t value)
static vm_offset_t arb_core, arb_cnfg, arb_observer;
-/*
- * One transfer at a time through the arbiter for this system, whoever asks (the flashlight's
- * driver, drivers/camera/hakios.torch.c, as well): with two at once the arbiter drops one ("the transfer
- * was dropped"), as Linux never lets happen (one lock for the bus).
- */
-static LCK_GRP_DECLARE(spmi_lck_grp, "hakios-spmi");
-static LCK_SPIN_DECLARE(spmi_lock, &spmi_lck_grp);
-
-void
-hakios_spmi_lock(void)
-{
- lck_spin_lock(&spmi_lock);
-}
-
-void
-hakios_spmi_unlock(void)
-{
- lck_spin_unlock(&spmi_lock);
-}
+/* one transfer at a time through the arbiter: hakios_spmi_lock() (drivers/core/hakios.platform.c) */
struct peripheral {
const char * name;
diff --git a/drivers/map b/drivers/map
index 3040d67..a291d3b 100644
--- a/drivers/map
+++ b/drivers/map
@@ -19,7 +19,6 @@ storage bsd/dev/hakios.ufshc.c
storage bsd/dev/hakios.ufshc.h
storage bsd/dev/hakios.sparse.c
storage bsd/dev/hakios.image.c
-storage bsd/dev/hakios.guard.c
storage bsd/dev/hakios.apfs_check.c
storage bsd/dev/hakios.virtio_blk.c
@@ -37,6 +36,7 @@ audio bsd/dev/hakios.sound.c
audio bsd/dev/hakios.speaker.c
audio bsd/dev/hakios.mic.c
audio bsd/dev/hakios.virtio_sound.c
+audio bsd/dev/hakios.guard.c
power bsd/dev/hakios.battery.c
power iokit/Kernel/hakios.battery.cpp
@@ -59,6 +59,9 @@ net bsd/dev/hakios.net.c
net bsd/dev/hakios.virtio_net.c
core bsd/dev/hakios.version.c
+core bsd/dev/hakios.platform.c
+core bsd/dev/hakios.stubs.c
+core iokit/Kernel/hakios.stubs.cpp
core bsd/dev/hakios.socinfo.c
power bsd/dev/hakios.thermal.c
power bsd/dev/hakios.pmic.c
diff --git a/drivers/modem/conf b/drivers/modem/conf
new file mode 100644
index 0000000..7442270
--- /dev/null
+++ b/drivers/modem/conf
@@ -0,0 +1,16 @@
+# drivers/modem/conf: QMI, and the cellular modem.
+# CONFIG_HAKIOS_<NAME>=y in a defconfig builds a driver into the kernel; "standard" files are always built.
+# tools/hakios-config.py reads this file; docs/drivers-config.md says what each word means and how it reaches XNU.
+
+driver QMI
+ file bsd/dev/hakios.qmi.c
+ help QMI messages over the IPC router: how the Wi-Fi firmware's service and the modem's are spoken to
+
+driver MODEM
+ file bsd/dev/hakios.mpss.c
+ file bsd/dev/hakios.cell.c
+ file bsd/dev/hakios.nas.c
+ file bsd/dev/hakios.ipa.c
+ requires QMI UFS
+ help the modem (modem=1): started, its file systems served from the flash, the IPA's data path as en1,
+ help the SIM and the network registration. Research; needs fw-modem/ from the phone
diff --git a/drivers/net/conf b/drivers/net/conf
new file mode 100644
index 0000000..068d8e0
--- /dev/null
+++ b/drivers/net/conf
@@ -0,0 +1,10 @@
+# drivers/net/conf: the network interfaces.
+# CONFIG_HAKIOS_<NAME>=y in a defconfig builds a driver into the kernel; "standard" files are always built.
+# tools/hakios-config.py reads this file; docs/drivers-config.md says what each word means and how it reaches XNU.
+
+standard bsd/dev/hakios.net.c
+ help en0, an interface that is Ethernet to the rest of the kernel, for whatever link carries its frames
+
+driver VIRTIO_NET
+ file bsd/dev/hakios.virtio_net.c
+ help QEMU's virtio network device as the link behind en0 (virtio_net=1). QEMU only
diff --git a/drivers/power/conf b/drivers/power/conf
new file mode 100644
index 0000000..0820423
--- /dev/null
+++ b/drivers/power/conf
@@ -0,0 +1,26 @@
+# drivers/power/conf: the battery, the processor's clock, temperatures, the PMICs, the guards of a run left alone.
+# CONFIG_HAKIOS_<NAME>=y in a defconfig builds a driver into the kernel; "standard" files are always built.
+# tools/hakios-config.py reads this file; docs/drivers-config.md says what each word means and how it reaches XNU.
+
+driver BATTERY
+ file bsd/dev/hakios.battery.c
+ file iokit/Kernel/hakios.battery.cpp iokitcpp
+ help the battery: kern.hakios.battery_*, and HakiosBattery, the IOPMPowerSource iOS reads the charge from
+ help (the state comes from the audio DSP's battery manager, with adsp=1)
+
+driver CPUFREQ
+ file bsd/dev/hakios.cpufreq.c
+ help the clock of the cores the kernel runs on (cpufreq=1), and the memory bus's votes (ddr=)
+
+driver THERMAL
+ file bsd/dev/hakios.thermal.c
+ help the SoC's temperature sensors (thermal=1): kern.hakios.thermal_*, and the run handed back to the
+ help loader when the phone gets too hot (thermal_stop=)
+
+driver PMIC
+ file bsd/dev/hakios.pmic.c
+ help the blocks of the power-management chips the SPMI arbiter shows, and the PMIC's clock (pmic=1); read only
+
+driver BATTGUARD
+ file bsd/dev/hakios.battguard.c
+ help the run handed back to the loader before the battery is flat (battery_stop=<percent>)
diff --git a/drivers/power/hakios.battery.c b/drivers/power/hakios.battery.c
index 82e44aa..19c8344 100644
--- a/drivers/power/hakios.battery.c
+++ b/drivers/power/hakios.battery.c
@@ -50,7 +50,7 @@ hakios_battery_temperature(void)
return battery_temperature_c;
}
-SYSCTL_NODE(_kern, OID_AUTO, hakios, CTLFLAG_RW | CTLFLAG_LOCKED, 0, "redwood phone bits");
+SYSCTL_DECL(_kern_hakios); /* the node is drivers/core/hakios.platform.c's: every driver hangs its sysctls there */
SYSCTL_INT(_kern_hakios, OID_AUTO, battery_soc, CTLFLAG_RD | CTLFLAG_LOCKED,
&battery_soc_percent, 0, "battery state of charge, 0..100 percent, or -1 if unknown");
SYSCTL_INT(_kern_hakios, OID_AUTO, battery_voltage_mv, CTLFLAG_RD | CTLFLAG_LOCKED,
diff --git a/drivers/storage/conf b/drivers/storage/conf
new file mode 100644
index 0000000..7197573
--- /dev/null
+++ b/drivers/storage/conf
@@ -0,0 +1,23 @@
+# drivers/storage/conf: the phone's flash, and the block devices of the images the port boots from.
+# CONFIG_HAKIOS_<NAME>=y in a defconfig builds a driver into the kernel; "standard" files are always built.
+# tools/hakios-config.py reads this file; docs/drivers-config.md says what each word means and how it reaches XNU.
+
+standard bsd/dev/hakios.image.c
+ help a file of one of the RAM disks by path, for the drivers that load firmware before there is a root
+
+standard bsd/dev/hakios.sparse.c
+ help /dev/rsp0, a block device over an image that holds only some of its blocks (apfs_sparse=)
+
+standard bsd/dev/hakios.apfs_check.c apfs
+ help a walk of the APFS volume on /dev/rvblk0 through VFS, to compare with tools/apfs/apfs.py
+
+driver UFS
+ file bsd/dev/hakios.ufs.c
+ file bsd/dev/hakios.ufshc.c
+ help the phone's UFS flash: a block device for each GPT partition (ufs=1, ufs=2), and the UFS host controller
+ help driven from the kernel (ufs_native=). THE ONLY CODE OF THE KERNEL THAT MAY WRITE TO THE PHONE
+ help (ufs_write=1, the partition `darwin` only): see tools/provenance.allow
+
+driver VIRTIO_BLK
+ file bsd/dev/hakios.virtio_blk.c
+ help a disk image of the host as /dev/rvblk0 (virtio_blk=1). QEMU only
diff --git a/drivers/storage/hakios.guard.c b/drivers/storage/hakios.guard.c
deleted file mode 100644
index 955be01..0000000
--- a/drivers/storage/hakios.guard.c
+++ /dev/null
@@ -1,318 +0,0 @@
-/*
- * The speakers' guard: what the samples go through on their way to the phone's two amplifiers
- * (drivers/audio/hakios.sound.c's feeder), in place of the protection Android has in the audio DSP.
- *
- * Under Android the DSP runs Awinic's algorithm (SKTune, "aw882xx_rx_switch") with each
- * speaker's calibration: it keeps the cone's excursion and the voice coil's temperature in
- * bounds, measuring both through the amplifiers' current and voltage feedback. None of that runs
- * here, and nothing here knows the speakers' parameters (Android's files that can be read have
- * none: the amplifiers' register profile, the battery tables of its "monitor", and in the device
- * tree a range of 4 to 9 ohms for the calibrated resistance). So the guard holds what reaches the
- * speakers to levels that are safe for small phone speakers whatever they are exactly, measured
- * the only way there is without feedback -- from the samples and the amplifiers' level -- and
- * kept well under what the speakers can take at Android's level:
- *
- * high-pass a second-order Butterworth filter at 200 Hz: a phone's speaker gives out next to
- * nothing below its resonance (several hundred Hz), and what it is given there only
- * moves the cone further and heats the coil
- * power the power that would reach a speaker, averaged three ways -- over 0.2 s (the
- * cone and coil at once), 3 s (the voice coil's warming) and 60 s (the magnet and
- * the frame) -- and the level turned down so that none of the three averages goes
- * over its limit: 3, 6 and 9 dB under the power of a full-scale sine at Android's
- * level. Sound of ordinary loudness never comes near them; a sustained full-scale
- * tone is turned down at once to the first, after seconds to the second and over a
- * minute to the third, and the level comes back up as the averages fall, as a
- * speaker cools. The averages go on falling while the amplifiers are off.
- * peaks no sample above 3 dB under full scale at Android's level: a limiter that turns
- * the level down at the sample that would go over (so none does) and lets it come
- * back with a time constant of 43 ms
- * monitor a further reduction that the amplifiers' watch asks for (hakios.speaker.c:
- * Android's table for a cold amplifier, and a low battery)
- *
- * Before all that, a gain (sound_gain, at most 12 dB): iOS's own processing for the iPhone X's
- * speaker keeps even a full-scale tone at its top volume 12.6 to 14.3 dB under full scale, so
- * without it iOS at the top would stay that much under Android at the top. What it lifts over
- * full scale is held to full scale by the peak limiter (or to its lower limit), never clipped.
- *
- * All the limits are in terms of the speakers: a signal at full scale with the amplifiers at
- * Android's level (the loudest they are ever set to) is 0 dB. With the amplifiers turned down
- * (sound_below) the same samples are that much quieter at the speakers, and the guard holds them
- * back only that much later. Everything is integer arithmetic (the kernel's threads do no
- * floating point); fractions are in Q30 unless said otherwise.
- *
- * One caller at a time (the feeder); hakios_guard_attenuation() and hakios_guard_monitor() may
- * be called from another thread.
- */
-#include <stdbool.h>
-#include <stdint.h>
-#include <sys/hakios.audio.h>
-
-#define ONE (1ll << 30)
-#define FULL_SCALE 32768
-
-/* The limits, in eighths of a dB under full scale at Android's level (powers: under a full-scale square wave's) */
-#define PEAK_LIMIT (3 * 8)
-#define RMS_LIMIT (6 * 8) /* a full-scale sine is 3 dB under a square wave: these are 3, 6, 9 dB under it */
-#define FAST_LIMIT (9 * 8)
-#define SLOW_LIMIT (12 * 8)
-/* ... and the averages' time constants, in frames (48 kHz) */
-#define RMS_FRAMES 9600 /* 0.2 s */
-#define FAST_FRAMES 144000 /* 3 s */
-#define SLOW_FRAMES 2880000 /* 60 s */
-#define RELEASE_SHIFT 11 /* the peak limiter lets go with a time constant of 2048 frames, 43 ms */
-#define MAX_FRAMES 1024 /* the most frames processed at once (the feeder's period: 960) */
-
-/* 10^(-n/160), n = 0..47, in Q30: an attenuation of n eighths of a dB, as a factor of amplitude */
-static const uint32_t eighths[48] = {
- 1073741824, 1058400094, 1043277569, 1028371116, 1013677647, 999194121, 984917536, 970844937, 956973408, 943300077,
- 929822112, 916536722, 903441154, 890532697, 877808678, 865266461, 852903448, 840717079, 828704830, 816864213,
- 805192776, 793688102, 782347808, 771169545, 760150998, 749289885, 738583957, 728030996, 717628817, 707375265,
- 697268218, 687305580, 677485290, 667805313, 658263644, 648858308, 639587356, 630448869, 621440953, 612561743,
- 603809400, 595182112, 586678091, 578295576, 570032831, 561888146, 553859832, 545946228,
-};
-#define SIX_DB 538145694 /* 10^(-6/20) in Q30 */
-
-/* the high-pass filter, 200 Hz at 48 kHz, Q = 1/sqrt(2): b0, b1, b2, a1, a2 in Q30 (RBJ's cookbook) */
-static const int64_t hpf_b0 = 1054047540, hpf_b1 = -2108095079, hpf_b2 = 1054047540;
-static const int64_t hpf_a1 = -2107733822, hpf_a2 = 1034714513;
-
-static struct {
- bool hpf;
- uint64_t gain; /* the gain before everything, Q30 (1 to 4) */
- volatile uint32_t attenuation; /* the amplifiers' level under Android's, eighths of a dB; HAKIOS_GUARD_SILENT: off */
- volatile uint32_t monitor; /* the monitor's reduction, eighths of a dB */
- int64_t x1[2], x2[2], y1[2], y2[2]; /* the filter's past, in 1/256 of a sample */
- uint64_t rms[2], fast[2], slow[2]; /* average powers at each speaker, Q30 of a full-scale square wave at Android's level */
- uint64_t level; /* the power guard's and the monitor's gain at the end of the last block */
- uint64_t envelope; /* the peak limiter's, 1/65536 of a sample */
- struct hakios_guard_report report;
-} guard = { .hpf = true, .attenuation = HAKIOS_GUARD_SILENT, .gain = ONE, .level = ONE, .report = { .least_gain = ONE, .least_peak_gain = 65536 } };
-
-static int32_t work[2 * MAX_FRAMES];
-
-/* 10^(-n/160) in Q30: n eighths of a dB under, as a factor of amplitude */
-static uint64_t
-amplitude(uint32_t n)
-{
- uint64_t value = eighths[n % 48];
-
- for (uint32_t i = 0; i < n / 48 && value != 0; i++) {
- value = value * SIX_DB >> 30;
- }
- return value;
-}
-
-static uint64_t
-isqrt(uint64_t value)
-{
- uint64_t root = 0, bit = 1ull << 62;
-
- while (bit > value) {
- bit >>= 2;
- }
- while (bit != 0) {
- if (value >= root + bit) {
- value -= root + bit;
- root = (root >> 1) + bit;
- } else {
- root >>= 1;
- }
- bit >>= 2;
- }
- return root;
-}
-
-/* how much of `limit' a power is, as the square of the gain that would bring it down to it (Q30, at most 1) */
-static uint64_t
-headroom(uint64_t power, uint64_t limit)
-{
- if (power <= limit) {
- return ONE;
- }
- return (limit << 30) / power;
-}
-
-void
-hakios_guard_configure(bool hpf, uint32_t gain)
-{
- guard.hpf = hpf;
- /* 10^(gain/160): one over the attenuation by as much */
- guard.gain = (1ull << 60) / amplitude(gain > HAKIOS_GUARD_MAX_GAIN ? HAKIOS_GUARD_MAX_GAIN : gain);
-}
-
-void
-hakios_guard_attenuation(uint32_t below)
-{
- guard.attenuation = below;
-}
-
-void
-hakios_guard_monitor(uint32_t below)
-{
- guard.monitor = below;
-}
-
-static void
-block(int16_t *frames, uint32_t count)
-{
- uint32_t attenuation = guard.attenuation;
- struct hakios_guard_report *r = &guard.report;
- /* (2 * attenuation is kept from wrapping in 32 bits: a wrapped value says nothing about the level, and for some it is
- a huge one, which makes the power limits see no power at all while the amplifiers are not turned down) */
- uint64_t to_speaker = attenuation == HAKIOS_GUARD_SILENT ? 0 :
- amplitude(attenuation > HAKIOS_GUARD_SILENT / 2 ? HAKIOS_GUARD_SILENT - 1 : 2 * attenuation);
- uint64_t sum[2] = { 0, 0 }, g2 = ONE, g, start = guard.level, ceiling;
- uint32_t binding = 0;
-
- /* the high-pass filter, and what comes out of it: its power, per channel */
- for (uint32_t i = 0; i < 2 * count; i++) {
- unsigned c = i & 1;
- int64_t x = (int64_t)frames[i] * (int64_t)guard.gain >> 22, y; /* (the gain, and 1/256 of a sample) */
- uint32_t level = frames[i] < 0 ? (uint32_t)-frames[i] : (uint32_t)frames[i];
-
- if (level > r->peak_in) {
- r->peak_in = level;
- }
- if (guard.hpf) {
- y = (hpf_b0 * x + hpf_b1 * guard.x1[c] + hpf_b2 * guard.x2[c] - hpf_a1 * guard.y1[c] - hpf_a2 * guard.y2[c]) >> 30;
- guard.x2[c] = guard.x1[c];
- guard.x1[c] = x;
- guard.y2[c] = guard.y1[c];
- guard.y1[c] = y;
- } else {
- y = x;
- }
- work[i] = (int32_t)((y + 128) >> 8);
- sum[c] += (uint64_t)((int64_t)work[i] * work[i]);
- }
-
- /* the averages at the speakers, and the gain that keeps all three under their limits */
- for (unsigned c = 0; c < 2; c++) {
- /* the block's power, Q30 of full scale (a square wave at 32768), then as it reaches the speaker */
- uint64_t power = (uint64_t)((unsigned __int128)(sum[c] / count) * to_speaker >> 30), h;
-
- guard.rms[c] = (uint64_t)((int64_t)guard.rms[c] + ((int64_t)power - (int64_t)guard.rms[c]) * count / RMS_FRAMES);
- guard.fast[c] = (uint64_t)((int64_t)guard.fast[c] + ((int64_t)power - (int64_t)guard.fast[c]) * count / FAST_FRAMES);
- guard.slow[c] = (uint64_t)((int64_t)guard.slow[c] + ((int64_t)power - (int64_t)guard.slow[c]) * count / SLOW_FRAMES);
- if ((h = headroom(guard.rms[c], amplitude(2 * RMS_LIMIT))) < g2) {
- g2 = h;
- binding = 1;
- }
- if ((h = headroom(guard.fast[c], amplitude(2 * FAST_LIMIT))) < g2) {
- g2 = h;
- binding = 2;
- }
- if ((h = headroom(guard.slow[c], amplitude(2 * SLOW_LIMIT))) < g2) {
- g2 = h;
- binding = 3;
- }
- }
- g = isqrt(g2 << 30) * amplitude(guard.monitor) >> 30;
- if (g > ONE) {
- g = ONE;
- }
- r->blocks++;
- if (binding == 1) {
- r->rms_blocks++;
- } else if (binding == 2) {
- r->fast_blocks++;
- } else if (binding == 3) {
- r->slow_blocks++;
- }
- if (g < r->least_gain) {
- r->least_gain = g;
- }
-
- /* the peaks: no sample over the limit at the speaker (and none over full scale) */
- ceiling = FULL_SCALE - 1;
- if (attenuation != HAKIOS_GUARD_SILENT && attenuation < PEAK_LIMIT) {
- ceiling = (uint64_t)FULL_SCALE * amplitude(PEAK_LIMIT - attenuation) >> 30;
- }
- for (uint32_t f = 0; f < count; f++) {
- /* (the power guard's gain moves from the last block's to this one's across the block) */
- uint64_t gain = (uint64_t)((int64_t)start + ((int64_t)g - (int64_t)start) * (int64_t)(f + 1) / (int64_t)count);
- int64_t y[2];
- uint64_t level, peak_gain = 65536;
-
- for (unsigned c = 0; c < 2; c++) {
- y[c] = (int64_t)work[2 * f + c] * (int64_t)gain >> 30;
- }
- level = (uint64_t)(y[0] < 0 ? -y[0] : y[0]);
- if ((uint64_t)(y[1] < 0 ? -y[1] : y[1]) > level) {
- level = (uint64_t)(y[1] < 0 ? -y[1] : y[1]);
- }
- guard.envelope -= guard.envelope >> RELEASE_SHIFT;
- if (level << 16 > guard.envelope) {
- guard.envelope = level << 16;
- }
- if (guard.envelope > ceiling << 16) {
- peak_gain = (ceiling << 32) / guard.envelope;
- r->limited_frames++;
- if (peak_gain < r->least_peak_gain) {
- r->least_peak_gain = (uint32_t)peak_gain;
- }
- }
- for (unsigned c = 0; c < 2; c++) {
- int64_t out = y[c] * (int64_t)peak_gain >> 16;
- uint32_t magnitude;
-
- out = out > FULL_SCALE - 1 ? FULL_SCALE - 1 : out < -FULL_SCALE ? -FULL_SCALE : out;
- frames[2 * f + c] = (int16_t)out;
- magnitude = (uint32_t)(out < 0 ? -out : out);
- if (magnitude > r->peak_out) {
- r->peak_out = magnitude;
- }
- }
- }
- guard.level = g;
- r->gain = g;
- r->rms = guard.rms[0] > guard.rms[1] ? guard.rms[0] : guard.rms[1];
- r->fast = guard.fast[0] > guard.fast[1] ? guard.fast[0] : guard.fast[1];
- r->slow = guard.slow[0] > guard.slow[1] ? guard.slow[0] : guard.slow[1];
-}
-
-void
-hakios_guard_process(int16_t *frames, uint32_t count)
-{
- while (count > 0) {
- uint32_t n = count < MAX_FRAMES ? count : MAX_FRAMES;
-
- block(frames, n);
- frames += 2 * n;
- count -= n;
- }
-}
-
-/* What has happened since the last call (and the averages and the gain as they are now). */
-void
-hakios_guard_take_report(struct hakios_guard_report *report)
-{
- *report = guard.report;
- guard.report = (struct hakios_guard_report){ .least_gain = ONE, .least_peak_gain = 65536 };
-}
-
-/* 10 log10 of a Q30 ratio, in tenths of a dB (for what is said) */
-int
-hakios_guard_decibels(uint64_t ratio)
-{
- static const uint16_t fraction[17] = {
- 0, 5732, 11136, 16248, 21098, 25711, 30109, 34312, 38336, 42196, 45904, 49472, 52911, 56229, 59434, 62534, 65535,
- };
- int64_t log2; /* Q16 */
- unsigned top = 63;
-
- if (ratio == 0) {
- return -999;
- }
- while (!(ratio >> top)) {
- top--;
- }
- {
- /* the 4 bits under the top one choose a segment, the next 12 where in it */
- uint64_t mantissa = top >= 16 ? ratio >> (top - 16) : ratio << (16 - top);
- unsigned index = (unsigned)(mantissa >> 12) & 15, within = (unsigned)mantissa & 4095;
-
- log2 = ((int64_t)top - 30) * 65536 + fraction[index] + (int64_t)(fraction[index + 1] - fraction[index]) * within / 4096;
- }
- return (int)(log2 * 30103 / 65536 / 1000);
-}
diff --git a/drivers/wifi/conf b/drivers/wifi/conf
new file mode 100644
index 0000000..78c46e9
--- /dev/null
+++ b/drivers/wifi/conf
@@ -0,0 +1,15 @@
+# drivers/wifi/conf: Wi-Fi.
+# CONFIG_HAKIOS_<NAME>=y in a defconfig builds a driver into the kernel; "standard" files are always built.
+# tools/hakios-config.py reads this file; docs/drivers-config.md says what each word means and how it reaches XNU.
+
+driver WIFI
+ file bsd/dev/hakios.wifi.c
+ file bsd/dev/hakios.wlfw.c
+ file bsd/dev/hakios.lx.c
+ file bsd/dev/hakios.sta.c
+ file bsd/dev/hakios.apple80211.c
+ file iokit/Kernel/hakios.wlan.cpp iokitcpp
+ requires QMI
+ help Wi-Fi of the WCN6750 (wifi=1, wifi_step=N): the DSP that runs the radio's firmware, Linux's ath11k
+ help (its object, made by tools/mk-ath11k.sh, is linked in only with this), a station, and the Apple80211
+ help surface iOS's wifid talks to. Needs fw-wifi/ from the phone
diff --git a/drivers/wifi/hakios.wifi.c b/drivers/wifi/hakios.wifi.c
index a079d33..57239db 100644
--- a/drivers/wifi/hakios.wifi.c
+++ b/drivers/wifi/hakios.wifi.c
@@ -182,16 +182,11 @@ extern kern_return_t thread_terminate(thread_t thread);
static LCK_GRP_DECLARE(wifi_lock_group, "hakios-wifi");
/*
- * What the audio DSP's start (hakios.adsp.c) uses as well, while this may be at work beside it:
- * the mailbox to the always-on processor, one message at a time, and the allocation of items in
- * the shared memory (whose hardware lock both take under the same number, so it does not keep
- * the two apart).
+ * What the audio DSP's start (hakios.adsp.c), the modem's and the sound's use as well, while this may be at work beside
+ * them: the always-on processor's mailbox, the shared memory's allocation, RPMh's sequencer and the SMMU's free match
+ * registers. They are drivers/core/hakios.platform.c's, so that each of those drivers can be built without this one.
*/
-LCK_MTX_DECLARE(hakios_aop_mailbox_lock, &wifi_lock_group);
-LCK_MTX_DECLARE(hakios_smem_alloc_lock, &wifi_lock_group);
-LCK_MTX_DECLARE(hakios_rsc_lock, &wifi_lock_group); /* RPMh's sequencer (TCS 0 of the RSC): the audio DSP's and the modem's drivers both ask through it */
-/* ... and the sound's (hakios.sound.c): a free match register and context of the SMMU, found and taken */
-LCK_MTX_DECLARE(hakios_smmu_lock, &wifi_lock_group);
+extern lck_mtx_t hakios_aop_mailbox_lock, hakios_smem_alloc_lock, hakios_rsc_lock, hakios_smmu_lock;
static uint32_t last_step, pause_ms = 2200, fine, watch_seconds = 3;
static uint32_t step; /* the one being performed */
diff --git a/mkxnuimg.py b/mkxnuimg.py
index 39f0dd7..f13d3e9 100755
--- a/mkxnuimg.py
+++ b/mkxnuimg.py
@@ -7,7 +7,7 @@ into an Android boot image for `fastboot boot`.
The boot shim copies the FD to its base and the payload to PAYLOAD_BASE.
-The UEFI pieces are taken from a Mu-Silicium tree built here (Mu-Silicium/, see devices/redwood/uefi/README.md)
+The UEFI pieces are taken from a Mu-Silicium tree built here (Mu-Silicium/, see uefi/README.md)
or, when there is none, from devices/redwood/prebuilt/.
usage: mkxnuimg.py [-p payload.bin] [-o out.img]
@@ -47,7 +47,7 @@ for name, path in parts.items():
hint = ''
if name == 'fd':
hint = ("\n The UEFI image is not in the repository: it carries the phone vendor's own drivers, which are not\n"
- " redistributed here. Build it from your own phone's firmware: devices/redwood/uefi/README.md")
+ " redistributed here. Build it from your own phone's firmware: uefi/README.md")
sys.exit(f'mkxnuimg.py: {path} not found{hint}')
shim = open(parts['shim'], 'rb').read()
fd = open(parts['fd'], 'rb').read()
diff --git a/socs/sc7280/configs/sc7280.config b/socs/sc7280/configs/sc7280.config
index 5b84b44..f70cb7e 100644
--- a/socs/sc7280/configs/sc7280.config
+++ b/socs/sc7280/configs/sc7280.config
@@ -1,10 +1,16 @@
# HakiOS fragment: the Qualcomm SC7280 family (SM7325, QCM6490: "yupik", "kodiak") -- what is true of the SoC, whatever phone it is in.
# The processor has eight cores and the biggest is core 7; the temperature sensors, the chip-identity memory and the PMIC arbiter are
# at the addresses of this family (the kernel's defaults, which a port to another SoC overrides: soc_smem, thermal_tm0/1 ...).
-# The sensors are read and the run is stopped at 105 degrees (CONFIG_THERMAL_STOP): this is the protection of a phone left alone.
+# The sensors are read (CONFIG_THERMAL); stopping the run when the phone is hot is CONFIG_THERMAL_STOP, which is NOT set here:
+# add CONFIG_THERMAL_STOP=105 to a device's fragment (or THERMAL_STOP=105 to the run) for a phone left alone.
CONFIG_SOC="sc7280"
CONFIG_CPUS=8
CONFIG_BOOTCPU=7
CONFIG_CPUFREQ=y
CONFIG_SOCINFO=y
CONFIG_THERMAL=y
+# the drivers of this SoC family: a device with it gets them from here, whatever phone-specific drivers it leaves out
+CONFIG_HAKIOS_CPUFREQ=y
+CONFIG_HAKIOS_SOCINFO=y
+CONFIG_HAKIOS_THERMAL=y
+CONFIG_HAKIOS_PMIC=y
diff --git a/socs/sc7280/soc.conf b/socs/sc7280/soc.conf
new file mode 100644
index 0000000..9658d4d
--- /dev/null
+++ b/socs/sc7280/soc.conf
@@ -0,0 +1,9 @@
+# socs/sc7280/soc.conf: what this SoC repository is: the facts of a Qualcomm SC7280-family chip, whatever phone it is in.
+# A phone with this SoC includes configs/sc7280.config from its defconfig. docs/porting/repositories.md has every word.
+
+soc sc7280
+ title Qualcomm SC7280 family (SM7325 "Snapdragon 778G", QCM6490; "yupik", "kodiak")
+ vendor Qualcomm
+ cores 8, the biggest is core 7
+ gpu Adreno 642L
+ maintainer the HakiOS developers (README.md)
diff --git a/tools/docs-check.py b/tools/docs-check.py
new file mode 100755
index 0000000..19dfa21
--- /dev/null
+++ b/tools/docs-check.py
@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""Every link of the documentation goes somewhere: docs/**/*.md and the README files, checked without anything to install.
+
+ - a relative link names a file or directory of the repository that is there;
+ - a link to a heading (page.md#heading, #heading) names a heading that page has (the anchor as GitHub and the website make it:
+ lower case, spaces to dashes, punctuation dropped);
+ - links inside code blocks are not links.
+
+usage: tools/docs-check.py exit 1 and the list if a link goes nowhere (CI runs it)
+"""
+import os
+import re
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+ROOT = os.path.dirname(HERE)
+LINK = re.compile(r"(?<!!)\[[^\]]*\]\(([^)\s]+)\)")
+FENCE = re.compile(r"^(```|~~~)")
+
+
+def slug(heading):
+ text = re.sub(r"`([^`]*)`", r"\1", heading.strip().lower())
+ text = re.sub(r"\[([^\]]*)\]\([^)]*\)", r"\1", text)
+ text = re.sub(r"[^\w\- ]", "", text, flags=re.UNICODE)
+ return text.replace(" ", "-")
+
+
+def prose(path):
+ """The lines of a page outside its code blocks."""
+ out, fenced = [], False
+ for line in open(path, encoding="utf-8"):
+ if FENCE.match(line.strip()):
+ fenced = not fenced
+ continue
+ if not fenced:
+ out.append(line)
+ return out
+
+
+def anchors(path, cache={}):
+ if path not in cache:
+ found = set()
+ for line in prose(path):
+ m = re.match(r"#{1,6}\s+(.*?)\s*#*\s*$", line)
+ if m:
+ base, n = slug(m.group(1)), 1
+ name = base
+ while name in found:
+ name, n = "%s-%d" % (base, n), n + 1
+ found.add(name)
+ cache[path] = found
+ return cache[path]
+
+
+def pages():
+ out = [os.path.join(ROOT, n) for n in sorted(os.listdir(ROOT)) if n.startswith("README") and n.endswith(".md")]
+ for d, _dirs, files in os.walk(os.path.join(ROOT, "docs")):
+ out += [os.path.join(d, f) for f in sorted(files) if f.endswith(".md")]
+ return out
+
+
+def main():
+ problems, links = [], 0
+ for page in pages():
+ shown = os.path.relpath(page, ROOT)
+ for n, line in enumerate(prose(page), 1):
+ for target in LINK.findall(line):
+ if re.match(r"[a-z]+:", target):
+ continue
+ links += 1
+ path, _, anchor = target.partition("#")
+ full = os.path.normpath(os.path.join(os.path.dirname(page), path)) if path else page
+ if not os.path.exists(full):
+ problems.append("%s: a link to %s, which is not there" % (shown, target))
+ elif anchor and full.endswith(".md") and anchor not in anchors(full):
+ problems.append("%s: a link to %s, and %s has no heading #%s" % (shown, target, os.path.relpath(full, ROOT), anchor))
+ for p in problems:
+ print("docs-check: " + p)
+ print("docs-check: %d pages, %d links%s" % (len(pages()), links, ", %d go nowhere" % len(problems) if problems else ", every one goes somewhere"))
+ return 1 if problems else 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tools/docs-gen.py b/tools/docs-gen.py
new file mode 100755
index 0000000..e97eef7
--- /dev/null
+++ b/tools/docs-gen.py
@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""The pages of the documentation that are made from the source, so that they cannot say something the source does not:
+
+ docs/reference/drivers.md every driver (drivers/*/conf, and the SoC and device repositories'): its symbol, files, what it
+ requires, which boot-arguments it reads, which configurations build it
+ docs/devices/index.md every device and SoC (devices/*/device.conf, socs/*/soc.conf): how far each part works
+ docs/devices/<name>.md one device's page
+
+usage: tools/docs-gen.py write them
+ tools/docs-gen.py --check exit 1 if one is not what the source makes (CI runs this)
+"""
+import importlib.util
+import os
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+ROOT = os.path.dirname(HERE)
+REPO = "https://github.com/shimoku74/hakios/blob/main/"
+MARK = {"works": "works", "partial": "partly", "missing": "no"}
+HEADER = "<!-- Made by tools/docs-gen.py from %s. Do not edit: change that, then run tools/docs-gen.py. -->\n\n"
+
+
+def load(name, file):
+ spec = importlib.util.spec_from_file_location(name, os.path.join(HERE, file))
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+def drivers_page(hc, hd):
+ readers = hc.arg_readers() or {}
+ by_file = {}
+ for arg, files in readers.items():
+ for f in files:
+ by_file.setdefault(f, set()).add(arg)
+ configs = {}
+ for kind, name in hd.present():
+ if kind != "device":
+ continue
+ fields = hd.describe(kind, name)
+ defconfig = hd.one(fields, "defconfig")
+ try:
+ config = hc.overlay({}, hc.resolve(ROOT, [defconfig]))
+ except hc.ConfigError:
+ continue
+ configs[name] = hc.drivers_built(config)
+ out = [HEADER % "drivers/*/conf and the SoC and device repositories' drivers",
+ "# Drivers", "",
+ "Every driver the kernel can be built with. `CONFIG_HAKIOS_<NAME>=y` in a defconfig builds it in; "
+ "[Drivers in the configuration](../drivers-config.md) says how, and [Writing a driver](../porting/drivers.md) how to add one.", ""]
+ out += ["## Always built", "", "| File | What |", "|---|---|"]
+ for path, tags, sub, help_ in hc.STANDARD:
+ out.append("| `%s` | %s%s |" % (os.path.basename(path), help_, " (with XNU's `%s`)" % " ".join(tags) if tags else ""))
+ subs = []
+ for d in hc.DRIVERS:
+ key = (d.origin or "", d.sub)
+ if key not in subs:
+ subs.append(key)
+ for origin, sub in subs:
+ title = sub if not origin else "%s (%s)" % (sub, os.path.relpath(origin, ROOT))
+ out += ["", "## %s" % title, ""]
+ out += ["| Driver | Files | Requires | Boot arguments | %s|" % "".join("%s | " % n for n in configs),
+ "|---|---|---|---|" + "---|" * len(configs)]
+ for d in hc.DRIVERS:
+ if (d.origin or "", d.sub) != (origin, sub):
+ continue
+ args = sorted({a for f, _t in d.files for a in by_file.get(os.path.basename(f), ())})
+ out.append("| **`%s`**<br>%s | %s | %s | %s | %s|" % (
+ d.symbol, d.help.replace("|", "\\|"), "<br>".join("`%s`" % os.path.basename(f) for f, _t in d.files),
+ ", ".join("`HAKIOS_%s`" % r for r in d.requires) or "", ", ".join("`%s=`" % a for a in args[:8]) +
+ (" and %d more" % (len(args) - 8) if len(args) > 8 else ""),
+ "".join("%s | " % ("built" if built[d.symbol] else "") for built in configs.values())))
+ out += ["", "The columns on the right are the devices' defconfigs: \"built\" means that defconfig builds the driver in.", ""]
+ return "\n".join(out)
+
+
+def device_page(hd, name, fields):
+ out = [HEADER % "devices/%s/device.conf" % name, "# %s (`%s`)" % (hd.one(fields, "title"), name), ""]
+ rows = [("Vendor", hd.one(fields, "vendor", "?")), ("SoC", "`%s`" % hd.one(fields, "soc", "?")),
+ ("Configuration", "`make %s`" % hd.one(fields, "defconfig", "?")), ("Maintainer", hd.one(fields, "maintainer", "?")),
+ ("Repository", "[`devices/%s/`](%sdevices/%s)" % (name, REPO.replace("/blob/", "/tree/"), name))]
+ if hd.one(fields, "firmware"):
+ rows.append(("Firmware", "`devices/%s/%s` pulls it from your own phone" % (name, hd.one(fields, "firmware"))))
+ out += ["| | |", "|---|---|"] + ["| %s | %s |" % r for r in rows] + ["", "## What works", "", "| Part | State | |", "|---|---|---|"]
+ for area, state, note in hd.statuses(fields):
+ out.append("| %s | %s | %s |" % (area, MARK[state], note.replace("|", "\\|")))
+ out += ["", "The state is what has been seen on this device, written down in `devices/%s/device.conf`; "
+ "a part the table does not name has not been looked at." % name, ""]
+ return "\n".join(out)
+
+
+def devices_page(hd):
+ devices = [(n, hd.describe("device", n)) for k, n in hd.present() if k == "device"]
+ socs = [(n, hd.describe("soc", n)) for k, n in hd.present() if k == "soc"]
+ areas = [a for a in hd.AREAS if any(a == x[0] for _n, f in devices for x in hd.statuses(f))]
+ out = [HEADER % "devices/*/device.conf and socs/*/soc.conf", "# Devices", "",
+ "Every device with a repository, and how far each part of it works. A device of yours: "
+ "[Port a device](../porting/index.md).", "",
+ "| Device | SoC | %s |" % " | ".join(areas), "|---|---|" + "---|" * len(areas)]
+ short = {"works": "yes", "partial": "partly", "missing": "no"}
+ for name, fields in devices:
+ states = {a: s for a, s, _n in hd.statuses(fields)}
+ out.append("| [%s](%s.md) | `%s` | %s |" % (hd.one(fields, "title"), name, hd.one(fields, "soc", "?"),
+ " | ".join(short.get(states.get(a), "") for a in areas)))
+ out += ["", "An empty cell is a part nobody has looked at on that device yet.", "", "## SoC families", "", "| SoC | What | |", "|---|---|---|"]
+ for name, fields in socs:
+ out.append("| `%s` | %s | [`socs/%s/`](%ssocs/%s) |" % (name, hd.one(fields, "title"), name, REPO.replace("/blob/", "/tree/"), name))
+ out.append("")
+ return "\n".join(out)
+
+
+def pages():
+ hc = load("hakios_config", "hakios-config.py")
+ hd = load("hakios_device", "hakios-device.py")
+ made = {os.path.join("docs", "reference", "drivers.md"): drivers_page(hc, hd),
+ os.path.join("docs", "devices", "index.md"): devices_page(hd)}
+ for kind, name in hd.present():
+ if kind == "device":
+ made[os.path.join("docs", "devices", name + ".md")] = device_page(hd, name, hd.describe(kind, name))
+ return made
+
+
+def main():
+ check = "--check" in sys.argv[1:]
+ stale = 0
+ for path, text in sorted(pages().items()):
+ full = os.path.join(ROOT, path)
+ have = open(full, encoding="utf-8").read() if os.path.isfile(full) else None
+ if have == text:
+ continue
+ if check:
+ print("docs-gen: %s is not what the source makes: run tools/docs-gen.py" % path)
+ stale += 1
+ else:
+ os.makedirs(os.path.dirname(full), exist_ok=True)
+ open(full, "w", encoding="utf-8", newline="\n").write(text)
+ print("docs-gen: %s written" % path)
+ if check and not stale:
+ print("docs-gen: the made pages are current")
+ return 1 if stale else 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tools/drivers-check.py b/tools/drivers-check.py
index 26f54b7..4e513ce 100755
--- a/tools/drivers-check.py
+++ b/tools/drivers-check.py
@@ -7,9 +7,13 @@ Rules (each one is a way the layout went wrong while it was being made):
- no file is listed twice, and no two files share a name (they would sit in one directory under it);
- every listed file exists as drivers/<subsystem>/<name>;
- every file under drivers/<subsystem>/ is listed (README.md excepted): an unlisted file would not reach the kernel;
- - xnu/files/ holds no driver any more (a copy there would be applied over the one in drivers/ or the other way round).
+ - xnu/files/ holds no driver any more (a copy there would be applied over the one in drivers/ or the other way round);
+ - drivers/<subsystem>/conf (what the kernel is built with: docs/drivers-config.md) reads, names only files of its own
+ subsystem, and every .c and .cpp of drivers/map is built by exactly one `standard` line or `driver` of it: a file in
+ none would be in the tree and never compiled.
usage: tools/drivers-check.py [--root DIR] exit 0 if all is well, 1 and the list of problems if not
"""
+import importlib.util
import os
import sys
@@ -63,15 +67,48 @@ def check(root):
if sub not in SUBSYSTEMS:
problems.append("drivers/%s is not a known subsystem directory" % sub)
for name in sorted(os.listdir(sub_dir)):
- if name != "README.md" and (sub, name) not in listed:
+ if name not in ("README.md", "conf") and (sub, name) not in listed:
problems.append("drivers/%s/%s is not in drivers/map, so it would never reach the kernel" % (sub, name))
for tree in seen_tree:
stale = os.path.join(root, "xnu", "files", tree)
if os.path.exists(stale):
problems.append("xnu/files/%s: a driver must not also be kept here" % tree)
+ problems += check_conf(root, entries)
return entries, problems
+def check_conf(root, entries):
+ """The conf files against the map: each compiled file built by one block, of the conf of its own subsystem."""
+ spec = importlib.util.spec_from_file_location("hakios_config", os.path.join(os.path.dirname(os.path.abspath(__file__)), "hakios-config.py"))
+ config = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(config)
+ try:
+ drivers, standard = config.load_drivers(root)
+ except config.ConfigError as e:
+ return [str(e)]
+ built = {}
+ for path, _tags, sub, _help in standard:
+ built[path] = (sub, "standard")
+ for d in drivers:
+ if d.origin: # a SoC's or device's own: its repository's, not drivers/map's (hakios-device.py check)
+ continue
+ for path, _tags in d.files:
+ built[path] = (d.sub, "driver " + d.name)
+ problems = []
+ for sub, tree in entries:
+ if not tree.endswith((".c", ".cpp")):
+ continue
+ if tree not in built:
+ problems.append("%s is in drivers/map but no drivers/*/conf builds it (add it to drivers/%s/conf)" % (tree, sub))
+ elif built[tree][0] != sub:
+ problems.append("%s is drivers/%s's, but drivers/%s/conf builds it (%s)" % (tree, sub, built[tree][0], built[tree][1]))
+ mapped = {tree for _sub, tree in entries}
+ for path, (sub, what) in sorted(built.items()):
+ if path not in mapped:
+ problems.append("drivers/%s/conf builds %s (%s), which drivers/map does not list" % (sub, path, what))
+ return problems
+
+
def main(argv):
root = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..")
if len(argv) == 3 and argv[1] == "--root":
@@ -82,7 +119,7 @@ def main(argv):
print("drivers-check: " + p)
print("drivers-check: %d problem(s)" % len(problems))
return 1
- print("drivers-check: %d drivers in %d subsystems, all listed, all present" % (
+ print("drivers-check: %d files in %d subsystems, all listed, all present, each built by one drivers/*/conf block" % (
len(entries), len({s for s, _ in entries})))
return 0
diff --git a/tools/guard-test.sh b/tools/guard-test.sh
index f53e85e..911b048 100755
--- a/tools/guard-test.sh
+++ b/tools/guard-test.sh
@@ -1,5 +1,5 @@
#!/bin/sh
-# The speakers' guard (drivers/storage/hakios.guard.c) on this machine: tools/guard_test.c built against it and run.
+# The speakers' guard (drivers/audio/hakios.guard.c) on this machine: tools/guard_test.c built against it and run.
# The kernel's header is all it needs, and an empty sys/ioccom.h beside it (the ioctl numbers are not used).
set -e
cd "$(dirname "$0")/.."
diff --git a/tools/guard_test.c b/tools/guard_test.c
index 1393d6c..7f0a566 100644
--- a/tools/guard_test.c
+++ b/tools/guard_test.c
@@ -1,5 +1,5 @@
/*
- * The speakers' guard (drivers/storage/hakios.guard.c) on this machine, with signals made up for it:
+ * The speakers' guard (drivers/audio/hakios.guard.c) on this machine, with signals made up for it:
* what comes out, second by second, for a sustained full-scale tone at the amplifiers' levels that
* are tried on the phone, for music-like noise, and for the tone once it stops (the cooling).
*
diff --git a/tools/hakios-config-test.py b/tools/hakios-config-test.py
index 1625ff4..ef218a0 100755
--- a/tools/hakios-config-test.py
+++ b/tools/hakios-config-test.py
@@ -6,6 +6,9 @@
writes to `darwin`; virt and trace do what they say; kernel.ver carries -sc7280
refusals an unknown symbol (with a suggestion), a firmware option in the open profile, a dependency that is
missing, a number out of range, a bad hex or string, a command line that cannot fit
+ drivers CONFIG_HAKIOS_* from drivers/*/conf: built in unless a configuration says otherwise; `is not set` leaves one
+ out; a driver without one it requires, and an argument only a left-out driver reads, are refused; `kernel`
+ writes the choice into a kernel tree where XNU's config reads it, and writes nothing when nothing changed
workflow merge over an existing .config; `is not set` in a fragment switches off; savedefconfig round-trips;
--config and --root work after the command as well as before it
"""
@@ -183,10 +186,10 @@ try:
listed = run("listing", "common").stdout
with open(os.path.join(ROOT, "configs", "common_defconfig"), encoding="utf-8", newline="") as f:
check("common_defconfig is what `listing common` makes of it (nothing edited by hand drifted)",
- f.read().replace("\r\n", "\n") == listed, "run: tools/hakios-config.py listing common > configs/common_defconfig")
+ f.read().replace("\r\n", "\n") == listed, "run: tools/hakios-config.py listing common -o configs/common_defconfig")
check("the listing has hundreds of symbols, each with a comment above it",
listed.count("\nCONFIG_") + listed.count("\n# CONFIG_") >= 300 and listed.count("\n# ") > 600, listed.count("\n"))
- with open(os.path.join(ROOT, "configs", "redwood_defconfig"), encoding="utf-8") as f:
+ with open(os.path.join(ROOT, "devices", "redwood", "configs", "redwood_defconfig"), encoding="utf-8") as f:
includes = [l.split()[1] for l in f if l.startswith("#include ")]
check("redwood_defconfig is the common one, the SoC's and the phone's, put together", includes == ["common_defconfig", "sc7280.config", "redwood.config"], includes)
check("the common configuration does not say which phone: no device, no SoC",
@@ -219,6 +222,70 @@ try:
check("there are as many symbols as arguments the source reads, less the ones the tools set",
len(hc.SYMBOLS) >= 300 and len({s[0] for s in hc.SYMBOLS}) == len(hc.SYMBOLS), len(hc.SYMBOLS))
+ # the drivers: compiled in, not arguments
+ check("redwood builds every driver, and they give no argument",
+ all("CONFIG_%s=y" % d.symbol in open(cfg).read() for d in hc.DRIVERS) and len(hc.DRIVERS) >= 20 and
+ not any(x.startswith("hakios_") for x in args_of(run("args", "--config", cfg))), len(hc.DRIVERS))
+ built = hc.drivers_built({})
+ check("a configuration that names no driver builds them all (their default)", all(built.values()), built)
+ off = dict(hc.parse(cfg)[0])
+ problems, _ = hc.check(dict(off, HAKIOS_ADSP="n"))
+ check("a driver without one it requires is refused (SOUND without ADSP)", any("CONFIG_HAKIOS_SOUND requires CONFIG_HAKIOS_ADSP" in p for p in problems), problems)
+ problems, _ = hc.check(dict(off, HAKIOS_GOODIX="n"))
+ check("an argument another built driver still reads is fine (touchscreen= is the buttons' too)", not problems, problems)
+ problems, _ = hc.check(dict(off, HAKIOS_GOODIX="n", HAKIOS_BUTTONS="n"))
+ check("an argument only left-out drivers read is refused (touchscreen= without GOODIX and BUTTONS)",
+ any("CONFIG_TOUCHSCREEN gives touchscreen=" in p and "CONFIG_HAKIOS_GOODIX" in p and "CONFIG_HAKIOS_BUTTONS" in p for p in problems), problems)
+ problems, _ = hc.check(dict(off, HAKIOS_GOODIX="n", HAKIOS_BUTTONS="n", TOUCHSCREEN="n"))
+ check("... and with that argument gone too, the choice passes", not [p for p in problems if "GOODIX" in p or "touchscreen" in p], problems)
+ problems, _ = hc.check(dict(off, HAKIOS_GOODIX="maybe"))
+ check("a driver is y or not set", any("CONFIG_HAKIOS_GOODIX is a driver" in p for p in problems), problems)
+ # a phone without that touch controller: a fragment in a root of its own (merge takes fragments of configs/)
+ fake4 = os.path.join(work, "fake4")
+ shutil.copytree(os.path.join(ROOT, "configs"), os.path.join(fake4, "configs"))
+ with open(os.path.join(fake4, "configs", "nogoodix.config"), "w", encoding="utf-8", newline="\n") as f:
+ f.write("# no Goodix here\n# CONFIG_HAKIOS_GOODIX is not set\n")
+ nog = os.path.join(work, "nogoodix")
+ shutil.copyfile(cfg, nog)
+ r = run("merge", "nogoodix", "--config", nog, root=fake4)
+ check("`# CONFIG_HAKIOS_GOODIX is not set` in a fragment leaves the driver out", r.returncode == 0 and
+ "# CONFIG_HAKIOS_GOODIX is not set" in open(nog).read() and "CONFIG_HAKIOS_BUTTONS=y" in open(nog).read(), r.stdout + r.stderr)
+ r = run("savedefconfig", "--config", nog, root=fake4)
+ check("savedefconfig keeps a driver that is left out", "# CONFIG_HAKIOS_GOODIX is not set" in r.stdout and "CONFIG_HAKIOS_BUTTONS" not in r.stdout, r.stdout)
+ r = run("help", "HAKIOS_SOUND")
+ check("help on a driver: its files, what it requires, what requires it",
+ "hakios.sound.c" in r.stdout and "requires: CONFIG_HAKIOS_ADSP, CONFIG_HAKIOS_SPEAKER" in r.stdout and "CONFIG_HAKIOS_MIC" in r.stdout, r.stdout)
+ # `kernel`: into a tree that has what XNU's config reads, as apply.sh leaves it before the first run (loose hakios lines)
+ tree = os.path.join(work, "tree")
+ for d in ("bsd/conf", "iokit/conf", "config", "bsd/dev"):
+ os.makedirs(os.path.join(tree, d))
+ with open(os.path.join(tree, "bsd/conf/files"), "w") as f:
+ f.write("bsd/dev/a.c standard\nbsd/dev/hakios.input.c\t\tstandard\nbsd/dev/hakios.goodix.c\tstandard\nbsd/dev/z.c standard\n")
+ with open(os.path.join(tree, "iokit/conf/files"), "w") as f:
+ f.write("iokit/Kernel/A.cpp optional iokitcpp\niokit/Kernel/hakios.gpu.cpp optional iokitcpp\n")
+ r = run("kernel", "--tree", tree, "--config", nog)
+ master = open(os.path.join(tree, "config/MASTER.hakios")).read()
+ files = open(os.path.join(tree, "bsd/conf/files")).read()
+ check("kernel: the choice is a list of attributes doconf expands, and an `options` line for every driver",
+ r.returncode == 0 and "# HAKIOS_DRIVERS = [ " in master and " hakios_buttons " in master and " hakios_goodix " not in master and
+ "options\t\tHAKIOS_GOODIX" in master and "# <hakios_goodix>" in master, r.stdout + r.stderr + master)
+ check("kernel: conf/files has one block, a driver's files `optional hakios_<name>`, the rest of the file as it was",
+ files.startswith("bsd/dev/a.c standard\n" + hc.FILES_BEGIN) and files.rstrip().endswith("bsd/dev/z.c standard") and
+ "bsd/dev/hakios.goodix.c optional hakios_goodix" in files and "bsd/dev/hakios.input.c standard" in files and
+ "iokit/Kernel/hakios.gpu.cpp optional hakios_adreno iokitcpp" in open(os.path.join(tree, "iokit/conf/files")).read(), files)
+ listed_line = [l for l in open(os.path.join(tree, "bsd/dev/hakios.drivers.h")) if l.startswith("#define HAKIOS_DRIVERS_LIST")]
+ check("kernel: the header kern.hakios.drivers comes from", listed_line and " buttons " in listed_line[0] and "goodix" not in listed_line[0], listed_line)
+ r = run("kernel", "--tree", tree, "--config", nog)
+ check("kernel: run again, it writes nothing (an unchanged choice rebuilds nothing)", r.returncode == 0 and "written" not in r.stdout, r.stdout)
+ r = run("kernel", "--tree", tree, "--config", os.path.join(work, "nosuch"))
+ check("kernel: without a .config every driver is built", " hakios_goodix " in open(os.path.join(tree, "config/MASTER.hakios")).read(), r.stdout + r.stderr)
+ bad = os.path.join(work, "badchoice")
+ shutil.copyfile(nog, bad)
+ with open(bad, "a") as f:
+ f.write("# CONFIG_HAKIOS_ADSP is not set\n")
+ r = run("kernel", "--tree", tree, "--config", bad)
+ check("kernel: refuses a choice a driver's requires breaks", r.returncode != 0 and "requires CONFIG_HAKIOS_ADSP" in r.stdout, r.stdout + r.stderr)
+
# help, show, list
r = run("help", "gpu")
check("help GPU: the argument, the firmware", "gpu=1" in r.stdout and "fw-gpu/" in r.stdout, r.stdout)
diff --git a/tools/hakios-config.py b/tools/hakios-config.py
index e64007c..13f825a 100755
--- a/tools/hakios-config.py
+++ b/tools/hakios-config.py
@@ -27,6 +27,7 @@ Where this differs from Linux's, on purpose:
import argparse
import collections
import difflib
+import importlib.util
import os
import re
import subprocess
@@ -37,6 +38,10 @@ ROOT = os.path.dirname(HERE)
KERNEL_LINE = 607 # BOOT_LINE_LENGTH 608 less the terminator: what the kernel's boot_args can hold
RUN_OVERHEAD = 260 # what a run adds itself: the loader's own arguments, xl's, the runner's (measured: ~190-250)
+class ConfigError(Exception):
+ pass
+
+
# name, kind, boot-arg, one-line help, firmware directory it needs, what it requires
# kinds: bool (y/n, becomes arg=1), int, hex, str, and meta (a fact about the build, not an argument)
SYMBOLS = [
@@ -121,15 +126,155 @@ def load_generated():
GENERATED = load_generated()
SYMBOLS += GENERATED
+
+
+# ---- the drivers: what the kernel is built with -----------------------------------------------------------------
+#
+# Every other symbol is a boot-argument. These are not: CONFIG_HAKIOS_<NAME>=y decides whether a driver is compiled into
+# the kernel at all, the way XNU decides it for its own parts -- an `options HAKIOS_<NAME>` line in config/MASTER, the
+# driver's files `optional hakios_<name>` in bsd/conf/files and iokit/conf/files, and -DHAKIOS_<NAME> for the code that
+# calls into it. What a driver is, which files it is and what it needs is written once, in drivers/<subsystem>/conf.
+
+def layers(root):
+ """[(kind, name, directory)] of the repositories a build is put together from, common first: this one ("common"), then each
+ SoC's (socs/<name>/, with a soc.conf) and each device's (devices/<name>/, with a device.conf) that is checked out here. They
+ are the layers of docs/porting/repositories.md: a SoC or device repository is a directory of the same shape (configs/,
+ drivers/<subsystem>/conf) that `tools/hakios-device.py sync` clones into place, or that lives in this tree until it has a
+ repository of its own."""
+ out = [("common", "common", root)]
+ for kind, top, marker in (("soc", "socs", "soc.conf"), ("device", "devices", "device.conf")):
+ base = os.path.join(root, top)
+ for name in sorted(os.listdir(base)) if os.path.isdir(base) else []:
+ if os.path.isfile(os.path.join(base, name, marker)):
+ out.append((kind, name, os.path.join(base, name)))
+ return out
+
+
+class Driver:
+ def __init__(self, name, sub, where, origin=None):
+ self.name, self.sub, self.where = name, sub, where
+ self.origin = origin # the SoC or device repository it comes from; None: this one's drivers/
+ self.files, self.requires, self.default, self.help = [], [], "y", ""
+
+ def source(self, path):
+ """Where a file of it is kept: drivers/<subsystem>/<name>, in this repository or in its own."""
+ return os.path.join(self.origin or "", "drivers", self.sub, os.path.basename(path))
+
+ @property
+ def symbol(self):
+ return "HAKIOS_" + self.name
+
+ @property
+ def tag(self):
+ return "hakios_" + self.name.lower()
+
+
+def load_drivers(root):
+ """([Driver], [(path, tags, subsystem, help)]) from drivers/*/conf: the drivers that can be left out, and the "standard"
+ files every kernel has. The format (docs/drivers-config.md):
+
+ standard <path in the XNU tree> [<XNU option>...] always built (with the XNU options given, if any)
+ driver <NAME> CONFIG_HAKIOS_<NAME>; the lines under it, indented:
+ file <path in the XNU tree> [<XNU option>...] one of its files (an iokit .cpp also wants iokitcpp)
+ requires <NAME>... drivers it cannot be built without
+ default y|n what a configuration that does not name it gets (y)
+ help <text> what it is; more lines of help go on
+ """
+ drivers, standard, seen_files = [], [], {}
+ confs = []
+ for kind, _name, top in layers(root):
+ base = os.path.join(top, "drivers")
+ for sub in sorted(os.listdir(base)) if os.path.isdir(base) else []:
+ if os.path.isfile(os.path.join(base, sub, "conf")):
+ confs.append((kind, top, sub, os.path.join(base, sub, "conf")))
+ for kind, top, sub, path in confs:
+ origin = None if kind == "common" else top
+ shown = os.path.relpath(path, root).replace(os.sep, "/")
+ block = None
+ for n, raw in enumerate(open(path, encoding="utf-8"), 1):
+ where = "%s:%d" % (shown, n)
+ line = raw.split("#", 1)[0].rstrip()
+ if not line.strip():
+ continue
+ words = line.split()
+ if not raw[0].isspace():
+ if words[0] == "driver" and len(words) == 2 and re.fullmatch(r"[A-Z][A-Z0-9_]*", words[1]):
+ block = Driver(words[1], sub, where, origin)
+ drivers.append(block)
+ elif words[0] == "standard" and len(words) >= 2:
+ if origin is not None:
+ raise ConfigError("%s: a SoC or device repository has drivers, not `standard` files (every kernel would have "
+ "them, which only the common repository decides)" % where)
+ block = [words[1], words[2:], sub, ""]
+ standard.append(block)
+ files = [words[1]]
+ else:
+ raise ConfigError("%s: want `driver NAME` (NAME in capitals) or `standard PATH`, got %r" % (where, line.strip()))
+ if isinstance(block, Driver):
+ continue
+ else:
+ if block is None:
+ raise ConfigError("%s: an indented line before any `driver` or `standard`" % where)
+ key, rest = words[0], line.strip()[len(words[0]):].strip()
+ if key == "help":
+ if isinstance(block, Driver):
+ block.help = (block.help + " " + rest).strip()
+ else:
+ block[3] = (block[3] + " " + rest).strip()
+ continue
+ if not isinstance(block, Driver):
+ raise ConfigError("%s: a `standard` file takes only `help` lines, got %r" % (where, key))
+ if key == "file" and len(words) >= 2:
+ block.files.append((words[1], words[2:]))
+ files = [words[1]]
+ elif key == "requires" and len(words) >= 2:
+ block.requires += words[1:]
+ continue
+ elif key == "default" and len(words) == 2 and words[1] in ("y", "n"):
+ block.default = words[1]
+ continue
+ else:
+ raise ConfigError("%s: want file PATH, requires NAME..., default y|n or help TEXT, got %r" % (where, line.strip()))
+ for f in files:
+ if not f.startswith(("bsd/dev/hakios.", "iokit/Kernel/hakios.")) or not f.endswith((".c", ".cpp")):
+ raise ConfigError("%s: %s is not a hakios.*.c or .cpp of bsd/dev/ or iokit/Kernel/" % (where, f))
+ if f in seen_files:
+ raise ConfigError("%s: %s is already built by %s" % (where, f, seen_files[f]))
+ seen_files[f] = where
+ names = {d.name: d for d in drivers}
+ if len(names) != len(drivers):
+ dup = [n for n, c in collections.Counter(d.name for d in drivers).items() if c > 1]
+ raise ConfigError("drivers/*/conf: the driver %s is declared twice" % ", ".join(dup))
+ for d in drivers:
+ if not d.files:
+ raise ConfigError("%s: the driver %s has no file" % (d.where, d.name))
+ for r in d.requires:
+ if r not in names:
+ close = difflib.get_close_matches(r, names, n=1)
+ raise ConfigError("%s: %s requires %s, which no drivers/*/conf declares%s" % (
+ d.where, d.name, r, " (did you mean %s?)" % close[0] if close else ""))
+ return drivers, [tuple(s) for s in standard]
+
+
+def driver_symbols(drivers):
+ return [(d.symbol, "driver", None, d.help or "the driver %s (%s)" % (d.name, d.where), None, None) for d in drivers]
+
+
+try:
+ DRIVERS, STANDARD = load_drivers(ROOT)
+except ConfigError as e: # said again by every command, with the rest of what it does
+ DRIVERS, STANDARD, DRIVERS_ERROR = [], [], str(e)
+else:
+ DRIVERS_ERROR = None
+DRIVER_BY_SYMBOL = {d.symbol: d for d in DRIVERS}
+for _d in DRIVERS:
+ GROUP_OF[_d.symbol] = "Drivers built in"
+SYMBOLS[3:3] = driver_symbols(DRIVERS) # after the build facts: they are facts about the build as well
BY_NAME = {s[0]: s for s in SYMBOLS}
FIRMWARE_VALUES = ("device", "none")
RANGES = {"CPUS": (1, 8), "BOOTCPU": (0, 7), "UFS": (1, 2), "THERMAL_POLL": (200, 60000), "THERMAL_STOP": (0, 160), "BATTERY_STOP": (0, 99), "BATTERY_STOP_POLL": (5, 600)}
-class ConfigError(Exception):
- pass
-
-
# ---- reading and writing --------------------------------------------------------------------------------------
def parse(path):
@@ -141,6 +286,10 @@ def parse(path):
for n, raw in enumerate(open(path, encoding="utf-8"), 1):
line = raw.strip()
m = re.fullmatch(r"#\s*CONFIG_([A-Z0-9_]+) is not set", line)
+ if m and m.group(1) in DRIVER_BY_SYMBOL:
+ values[m.group(1)] = "n" # a driver left out: not "the kernel's default", which for a driver is to build it
+ unset.discard(m.group(1))
+ continue
if m:
unset.add(m.group(1))
values.pop(m.group(1), None)
@@ -166,6 +315,10 @@ def parse(path):
def typed(name, value):
"""The value of a symbol as Python has it, or a ConfigError that says what is wrong."""
kind = BY_NAME[name][1]
+ if kind == "driver":
+ if value not in ("y", "n"):
+ raise ConfigError("CONFIG_%s is a driver: y (built in), or not set (left out) (got %s)" % (name, value))
+ return value == "y"
if kind == "bool":
if value != "y":
raise ConfigError("CONFIG_%s is a bool: y, or not set (got %s)" % (name, value))
@@ -224,15 +377,23 @@ def config_dir(root):
return os.path.join(root, "configs")
+def config_dirs(root):
+ """configs/ of this repository, then of every SoC and device repository there is (layers())."""
+ return [os.path.join(top, "configs") for _kind, _name, top in layers(root) if os.path.isdir(os.path.join(top, "configs"))]
+
+
def find_config(root, name):
- """configs/<name>, configs/<name>_defconfig or configs/<name>.config: the file for NAME."""
+ """<name>, <name>_defconfig or <name>.config in configs/ here or in a SoC's or device's repository: the file for NAME. A name
+ two repositories both have is an error, not a guess: which one a build took would depend on what is checked out."""
base = os.path.basename(name)
for candidate in (base, base + "_defconfig", base + ".config"):
- path = os.path.join(config_dir(root), candidate)
- if os.path.isfile(path):
- return path
- available = sorted(os.listdir(config_dir(root))) if os.path.isdir(config_dir(root)) else []
- raise ConfigError("no configs/%s, configs/%s_defconfig or configs/%s.config (there is: %s)" %
+ found = [os.path.join(d, candidate) for d in config_dirs(root) if os.path.isfile(os.path.join(d, candidate))]
+ if len(found) > 1:
+ raise ConfigError("%s is in more than one repository: %s" % (candidate, ", ".join(rel(root, f) for f in found)))
+ if found:
+ return found[0]
+ available = sorted({n for d in config_dirs(root) for n in os.listdir(d)})
+ raise ConfigError("no %s, %s_defconfig or %s.config in configs/, socs/*/configs/ or devices/*/configs/ (there is: %s)" %
(base, base, base, ", ".join(available) or "nothing"))
@@ -288,14 +449,23 @@ def write_config(config, path, sources):
"# Made by tools/hakios-config.py from %s." % ", ".join(sources),
"# Do not edit it: change a defconfig or a fragment in configs/, and make the .config again.",
"#"]
+ built = drivers_built(config)
for name, kind, _arg, _help, _needs, _requires in SYMBOLS:
- if name in config:
+ if kind == "driver":
+ lines.append("CONFIG_%s=y" % name if built[name] else "# CONFIG_%s is not set" % name)
+ elif name in config:
lines.append("CONFIG_%s=%s" % (name, config[name]))
elif kind != "meta":
lines.append("# CONFIG_%s is not set" % name)
open(path, "w", encoding="utf-8", newline="\n").write("\n".join(lines) + "\n")
+def drivers_built(config):
+ """{CONFIG name: True if built in} for every driver: its value in `config`, or its default where the configuration does
+ not name it (a .config made before there were driver symbols builds every driver, as the kernel was built then)."""
+ return {d.symbol: config.get(d.symbol, d.default) == "y" for d in DRIVERS}
+
+
def kernel_ver(root, config_path):
"""The kernel.ver string this .config gives (tools/kernel-version.py reads CONFIG_SOC from it)."""
out = subprocess.run([sys.executable, os.path.join(HERE, "kernel-version.py"), "--config", config_path, "--root", root],
@@ -315,8 +485,11 @@ def check(config):
except ConfigError as e:
problems.append(str(e))
firmware = parsed.get("FIRMWARE", "device")
+ problems += check_drivers(config, parsed)
for name in parsed:
_n, _kind, _arg, _help, needs, requires = BY_NAME[name]
+ if _kind == "driver":
+ continue
if needs and firmware == "none":
problems.append('CONFIG_%s needs the phone\'s own firmware (%s/), and this configuration says CONFIG_FIRMWARE="none": '
"it loads nothing from the device" % (name, needs))
@@ -348,6 +521,55 @@ def check(config):
return problems, args
+def check_drivers(config, parsed):
+ """The problems of the drivers' choice: a driver built without one it requires, and a boot-argument set for a driver that
+ is not built (it would be read by nothing: the kernel does not say so, the argument is just never looked at)."""
+ problems = []
+ if DRIVERS_ERROR:
+ return [DRIVERS_ERROR]
+ built = drivers_built(config)
+ for d in DRIVERS:
+ if built[d.symbol]:
+ for r in d.requires:
+ if not built["HAKIOS_" + r]:
+ problems.append("CONFIG_%s requires CONFIG_HAKIOS_%s (%s)" % (d.symbol, r, d.where))
+ left_out = {os.path.basename(f) for d in DRIVERS if not built[d.symbol] for f, _tags in d.files}
+ if not left_out:
+ return problems
+ readers = arg_readers()
+ if readers is None:
+ return problems
+ owner = {os.path.basename(f): d.symbol for d in DRIVERS for f, _tags in d.files}
+ wanted = [(name, BY_NAME[name][2]) for name in parsed if BY_NAME[name][2]]
+ wanted += [("BOOTARGS", w.partition("=")[0]) for w in parsed.get("BOOTARGS", [])]
+ for name, arg in wanted:
+ read_by = readers.get(arg)
+ if read_by and read_by <= left_out:
+ problems.append("CONFIG_%s gives %s=, which only %s read%s, and %s not built (%s)" % (
+ name, arg, ", ".join(sorted(read_by)), "s" if len(read_by) == 1 else "", "it is" if len(read_by) == 1 else "they are",
+ ", ".join(sorted({"CONFIG_%s" % owner[f] for f in read_by}))))
+ return problems
+
+
+_READERS = []
+
+
+def arg_readers():
+ """{argument: {file names}} of the arguments only the kernel reads (tools/boot-args.py's scan of the source); None when
+ the source cannot be scanned (not a git checkout)."""
+ if not _READERS:
+ try:
+ spec = importlib.util.spec_from_file_location("boot_args", os.path.join(HERE, "boot-args.py"))
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ found = module.scan(ROOT)
+ _READERS.append({arg: set(where["kernel"]) for arg, where in found.items()
+ if where["kernel"] and not where["loader"] and not where["user"]})
+ except (OSError, subprocess.CalledProcessError, AttributeError):
+ _READERS.append(None)
+ return _READERS[0]
+
+
def boot_args(parsed):
"""['cpus=8', 'gpu=1', ...] in the order of the symbol table."""
args = []
@@ -434,8 +656,13 @@ def cmd_show(a):
problems, args = check(config)
given = {x.split("=", 1)[0]: x for x in args}
print("HakiOS configuration %s, kernel.ver=%s" % (rel(os.getcwd(), a.config), kernel_ver(a.root, a.config)))
+ built = drivers_built(config)
+ print("drivers built in: %s" % (" ".join(d.name.lower() for d in DRIVERS if built[d.symbol]) or "none"))
+ left_out = [d.name.lower() for d in DRIVERS if not built[d.symbol]]
+ if left_out:
+ print("drivers left out: %s" % " ".join(left_out))
for name, _kind, arg, _help, _needs, _requires in SYMBOLS:
- if name in config:
+ if name in config and _kind != "driver":
print(" CONFIG_%-13s = %-14s %s" % (name, config[name], "-> " + given[arg] if arg in given else "(a fact about the build)"))
print("boot-arguments: %s" % " ".join(args))
print("firmware wanted from the phone: %s" % (", ".join(sorted({BY_NAME[n][4] for n in config if BY_NAME[n][4]})) or "none"))
@@ -466,7 +693,12 @@ def cmd_savedefconfig(a):
config = load(a.config)
base = parse(find_config(a.root, "defconfig"))[0]
lines = ["# A minimal defconfig: what this configuration sets that configs/defconfig does not, or sets differently."]
- for name, *_ in SYMBOLS:
+ built, base_built = drivers_built(config), drivers_built(base)
+ for name, kind, *_ in SYMBOLS:
+ if kind == "driver":
+ if built[name] != base_built[name]:
+ lines.append("CONFIG_%s=y" % name if built[name] else "# CONFIG_%s is not set" % name)
+ continue
if name in config and base.get(name) != config[name]:
lines.append("CONFIG_%s=%s" % (name, config[name]))
elif name not in config and name in base:
@@ -484,20 +716,20 @@ def first_comment(path):
def cmd_list(a):
- d = config_dir(a.root)
- names = sorted(os.listdir(d)) if os.path.isdir(d) else []
+ files = sorted((n, os.path.join(d, n)) for d in config_dirs(a.root) for n in os.listdir(d))
+ where = lambda path: "" if os.path.dirname(path) == config_dir(a.root) else " [%s]" % rel(a.root, os.path.dirname(os.path.dirname(path)))
print("defconfigs (tools/hakios-config.py defconfig NAME, or make NAME_defconfig):")
- for n in names:
+ for n, path in files:
if n == "defconfig" or n.endswith("_defconfig"):
- print(" %-16s %s" % (n[:-len("_defconfig")] if n.endswith("_defconfig") else n, first_comment(os.path.join(d, n))))
+ print(" %-16s %s%s" % (n[:-len("_defconfig")] if n.endswith("_defconfig") else n, first_comment(path), where(path)))
print("fragments (put over a configuration: tools/hakios-config.py merge NAME, or defconfig NAME FRAGMENT):")
- for n in names:
+ for n, path in files:
if n.endswith(".config"):
- print(" %-16s %s" % (n[:-len(".config")], first_comment(os.path.join(d, n))))
+ print(" %-16s %s%s" % (n[:-len(".config")], first_comment(path), where(path)))
return 0
-GROUP_ORDER = ["Build facts", "CPU, memory and boot", "Storage and APFS", "Touch and buttons", "GPU and display", "Audio and battery",
+GROUP_ORDER = ["Build facts", "Drivers built in", "CPU, memory and boot", "Storage and APFS", "Touch and buttons", "GPU and display", "Audio and battery",
"Wi-Fi", "Cellular", "Cameras", "Haptics and torch", "Chip, thermal and PMIC", "Network", "Security stand-ins",
"Debugging", "Loader", "User space", "Version", "Extra arguments"]
@@ -509,8 +741,12 @@ def listing(config, title_lines):
by_group = collections.defaultdict(list)
for sym in SYMBOLS:
by_group[GROUP_OF.get(sym[0], "User space")].append(sym)
+ built = drivers_built(config)
+ config = {k: v for k, v in config.items() if k not in built}
+ config.update({k: "y" for k, on in built.items() if on})
out = list(title_lines)
- out += ["# %d symbols in %d groups; %d are set." % (len(SYMBOLS), len([g for g in by_group if by_group[g]]), len(config)), "#", ""]
+ out += ["# %d symbols in %d groups; %d are set, %d of them drivers built in." % (
+ len(SYMBOLS), len([g for g in by_group if by_group[g]]), len(config), sum(built.values())), "#", ""]
for group in GROUP_ORDER + sorted(g for g in by_group if g not in GROUP_ORDER):
syms = by_group.get(group)
if not syms:
@@ -519,6 +755,10 @@ def listing(config, title_lines):
for name, kind, arg, help_, needs, requires in syms:
text = help_ if len(help_) <= 118 else help_[:117].rsplit(" ", 1)[0] + " ..."
note = ""
+ if kind == "driver":
+ d = DRIVER_BY_SYMBOL[name]
+ note += " [%s%s]" % (", ".join(os.path.basename(f) for f, _t in d.files),
+ "; requires " + ", ".join("CONFIG_HAKIOS_" + r for r in d.requires) if d.requires else "")
if needs:
note += " [needs %s/ from the phone]" % needs
if requires:
@@ -534,9 +774,18 @@ def cmd_listing(a):
files = resolve(a.root, [a.name] + a.fragments)
config = overlay({}, files)
title = ["#", "# HakiOS %s defconfig: every setting there is, with what it does." % a.name,
- "# Made by tools/hakios-config.py listing %s; the values are the ones that file sets, and tests/CI check that it names every symbol." % a.name,
+ "# Made by tools/hakios-config.py listing %s -o <this file>; the values are the ones that file sets, and tests/CI check that it names every symbol." % a.name,
"#"]
- sys.stdout.write(listing(config, title))
+ text = listing(config, title)
+ if a.output_listing:
+ # read first, written after: `listing common > configs/common_defconfig` has the shell empty the file before it is read,
+ # and the configuration written is then the base one's alone (which is how common_defconfig once lost its values)
+ with open(a.output_listing + ".new", "w", encoding="utf-8", newline="\n") as f:
+ f.write(text)
+ os.replace(a.output_listing + ".new", a.output_listing)
+ print("hakios-config: %s written" % rel(os.getcwd(), a.output_listing))
+ else:
+ sys.stdout.write(text)
return 0
@@ -568,6 +817,15 @@ def cmd_help(a):
_n, kind, arg, help_, needs, requires = BY_NAME[name]
print("CONFIG_%s (%s)" % (name, kind))
print(" " + help_)
+ if kind == "driver":
+ d = DRIVER_BY_SYMBOL[name]
+ print(" compiled into the kernel, not a boot-argument: XNU's option %s (%s)" % (d.symbol, d.where))
+ print(" files: %s" % ", ".join(f for f, _t in d.files))
+ print(" requires: %s" % (", ".join("CONFIG_HAKIOS_" + r for r in d.requires) or "nothing"))
+ needed_by = [o.symbol for o in DRIVERS if d.name in o.requires]
+ if needed_by:
+ print(" required by: %s" % ", ".join("CONFIG_" + n for n in needed_by))
+ print(" default: %s" % ("y (built in)" if d.default == "y" else "not set (left out)"))
if arg:
print(" boot-argument: %s=%s" % (arg, {"bool": "1", "hex": "0x...", "int": "N", "str": "...", "arg": "1, N or text", "args": "..."}[kind]))
if needs:
@@ -577,6 +835,166 @@ def cmd_help(a):
return 0
+# ---- the kernel tree: the drivers' choice where XNU's own build reads it ----------------------------------------------
+
+FILES_BEGIN = "# HakiOS drivers: made by tools/hakios-config.py kernel from drivers/*/conf. Edit those, not these lines."
+FILES_END = "# end of the HakiOS drivers"
+GENERATED_IN_TREE = ("config/MASTER.hakios", "bsd/dev/hakios.drivers.h") # made per configuration; never exported (xnu/export.sh)
+USES_OPTION = re.compile(r"^\s*#\s*(?:if|ifdef|ifndef|elif)\b.*\bHAKIOS_[A-Z][A-Z0-9_]*", re.M)
+
+
+def files_block(component):
+ """The lines of bsd/conf/files or iokit/conf/files for every hakios file of that component: `standard`, or
+ `optional hakios_<driver>` (and the file's own XNU options; config(8) builds a file whose options are all on)."""
+ lines = [FILES_BEGIN]
+ for path, tags, _sub, _help in STANDARD:
+ if path.startswith(component + "/"):
+ lines.append("%-40s %s" % (path, "optional " + " ".join(tags) if tags else "standard"))
+ for d in DRIVERS:
+ for path, tags in d.files:
+ if path.startswith(component + "/"):
+ lines.append("%-40s optional %s" % (path, " ".join([d.tag] + tags)))
+ return lines + [FILES_END]
+
+
+def put_block(text, block):
+ """`text` (a conf/files) with its HakiOS block replaced by `block`; a tree from before there was a block has its loose
+ hakios lines taken out and the block put where the first of them was."""
+ lines = text.split("\n")
+ if FILES_BEGIN in lines:
+ start = lines.index(FILES_BEGIN)
+ end = lines.index(FILES_END, start)
+ return "\n".join(lines[:start] + block + lines[end + 1:])
+ loose = [i for i, l in enumerate(lines) if re.match(r"(bsd/dev|iokit/Kernel)/hakios\.", l)]
+ if not loose:
+ raise ConfigError("no HakiOS lines in it to replace")
+ kept = [l for i, l in enumerate(lines) if i not in set(loose)]
+ at = loose[0]
+ return "\n".join(kept[:at] + block + kept[at:])
+
+
+def master_hakios(built, sources):
+ """config/MASTER.hakios: the configuration's choice, in doconf's terms. HAKIOS_DRIVERS is a list of attributes that the
+ kernel configurations of MASTER.arm64.bcm2837 include; an `options` line is taken when its attribute is in the list."""
+ on = [d.tag for d in DRIVERS if built[d.symbol]]
+ lines = ["#", "# The HakiOS drivers of this build, made by tools/hakios-config.py kernel from %s." % sources,
+ "# Not part of the patch: xnu/export.sh leaves it out, and every `make kernel` makes it again.", "#",
+ "# HAKIOS_DRIVERS = [ %s ]" % " ".join(on), "#"]
+ for d in DRIVERS:
+ what = re.sub(r"[#<>]", "", d.help) # doconf reads the last `# <attribute>` of a line: nothing in the comment may look like it
+ lines.append("options\t\t%-24s # %-48s # <%s>" % (d.symbol, what[:48].rsplit(" ", 1)[0] if len(what) > 48 else what, d.tag))
+ return "\n".join(lines) + "\n"
+
+
+def drivers_header(built, sources):
+ on = [d.name.lower() for d in DRIVERS if built[d.symbol]]
+ return ("/* The drivers this kernel is built with: made by tools/hakios-config.py kernel from %s. Not part of the patch. */\n"
+ "#define HAKIOS_DRIVERS_LIST \"%s\"\n#define HAKIOS_DRIVERS_COUNT %d\n#define HAKIOS_DRIVERS_CONFIG \"%s\"\n" %
+ (sources, " ".join(on), len(on), sources))
+
+
+def write_if_changed(path, text):
+ old = open(path, encoding="utf-8").read() if os.path.isfile(path) else None
+ if old == text:
+ return False
+ with open(path + ".new", "w", encoding="utf-8", newline="\n") as f:
+ f.write(text)
+ os.replace(path + ".new", path)
+ return True
+
+
+def stale_objects(tree):
+ """The objects of the files whose code asks about a driver (#if HAKIOS_*): XNU's build sees the option in the compiler's
+ command line, not as a file the object depends on, so a changed choice would leave them as they were built."""
+ stems = set()
+ for top in ("bsd", "iokit", "osfmk", "libkern", "pexpert"):
+ for d, _dirs, files in os.walk(os.path.join(tree, top)):
+ for name in files:
+ if name.endswith((".c", ".cpp", ".h")):
+ try:
+ text = open(os.path.join(d, name), encoding="utf-8", errors="replace").read()
+ except OSError:
+ continue
+ if "HAKIOS_" in text and USES_OPTION.search(text):
+ stems.add(os.path.splitext(name)[0])
+ removed = 0
+ headers = {s for s in stems if os.path.isfile(os.path.join(tree, "bsd", "sys", s + ".h"))}
+ obj = os.path.join(tree, "BUILD", "obj")
+ for d, _dirs, files in os.walk(obj):
+ for name in files:
+ stem, ext = os.path.splitext(name)
+ if ext in (".o", ".cpo") and stem in stems: # XNU names a C++ object .cpo
+ os.remove(os.path.join(d, name))
+ removed += 1
+ if headers:
+ # a header that tests an option (a stand-in for a driver left out) changes every object that includes it: those are
+ # found by the dependency files the compiler wrote, which name the headers each object was built from
+ for d, _dirs, files in os.walk(obj):
+ for name in files:
+ if name.endswith((".d", ".cpd")):
+ text = open(os.path.join(d, name), encoding="utf-8", errors="replace").read()
+ if any("/" + h + ".h" in text for h in headers):
+ o = os.path.join(d, name[:-2] + ".o" if name.endswith(".d") else name[:-4] + ".cpo")
+ if os.path.isfile(o):
+ os.remove(o)
+ removed += 1
+ return removed
+
+
+def cmd_kernel(a):
+ """kernel [--tree DIR]: put the drivers' choice of the .config (every driver's default if there is no .config) into the
+ kernel tree, where XNU's build reads it: config/MASTER.hakios, the HakiOS block of bsd/conf/files and iokit/conf/files,
+ bsd/dev/hakios.drivers.h. Files are written only when they change, so an unchanged choice rebuilds nothing."""
+ if DRIVERS_ERROR:
+ raise ConfigError(DRIVERS_ERROR)
+ tree = a.tree or os.environ.get("XNU_SRC") or os.path.join(a.root, "xnu-src", "xnu-8796.121.2")
+ if not os.path.isfile(os.path.join(tree, "bsd", "conf", "files")):
+ raise ConfigError("no kernel tree at %s (xnu/apply.sh makes it)" % tree)
+ if os.path.isfile(a.config):
+ config, sources = load(a.config), rel(a.root, a.config)
+ else:
+ config, sources = {}, "the drivers' defaults (no .config)"
+ problems = check_drivers(config, {})
+ if problems:
+ report(problems)
+ return 1
+ built = drivers_built(config)
+ changed = []
+ for component in ("bsd", "iokit"):
+ path = os.path.join(tree, component, "conf", "files")
+ try:
+ text = put_block(open(path, encoding="utf-8").read(), files_block(component))
+ except ConfigError as e:
+ raise ConfigError("%s/conf/files: %s" % (component, e))
+ if write_if_changed(path, text):
+ changed.append(component + "/conf/files")
+ choice_changed = write_if_changed(os.path.join(tree, "config", "MASTER.hakios"), master_hakios(built, sources))
+ if choice_changed:
+ changed.append("config/MASTER.hakios")
+ if write_if_changed(os.path.join(tree, "bsd", "dev", "hakios.drivers.h"), drivers_header(built, sources)):
+ changed.append("bsd/dev/hakios.drivers.h")
+ removed = stale_objects(tree) if choice_changed and os.path.isdir(os.path.join(tree, "BUILD", "obj")) else 0
+ on = [d.name.lower() for d in DRIVERS if built[d.symbol]]
+ off = [d.name.lower() for d in DRIVERS if not built[d.symbol]]
+ print("hakios-config: kernel: %d of %d drivers built in, from %s%s" % (len(on), len(DRIVERS), sources,
+ "; left out: " + " ".join(off) if off else ""))
+ if changed:
+ print("hakios-config: kernel: %s written%s" % (", ".join(changed), "; %d objects to be built again" % removed if removed else ""))
+ return 0
+
+
+def cmd_external(a):
+ """external-files: "<file in a SoC's or device's repository>\t<path in the kernel tree>" for each file of their drivers, for
+ xnu/apply.sh and xnu/sync-drivers.sh to copy into the tree and xnu/export.sh to leave where it is (it is not this repository's)."""
+ if DRIVERS_ERROR:
+ raise ConfigError(DRIVERS_ERROR)
+ for d in DRIVERS:
+ if d.origin:
+ for path, _tags in d.files:
+ print("%s\t%s" % (d.source(path), path))
+ return 0
+
+
def main():
# --root and --config are accepted before the command and after it
common = argparse.ArgumentParser(add_help=False)
@@ -602,13 +1020,18 @@ def main():
("savedefconfig", cmd_savedefconfig, "the .config as a minimal defconfig"),
("list", cmd_list, "the defconfigs and fragments in configs/")):
sub.add_parser(name, parents=[common], help=text).set_defaults(fn=fn)
- p = sub.add_parser("listing", parents=[common], help="the documented defconfig of NAME, every symbol, on stdout")
+ p = sub.add_parser("listing", parents=[common], help="the documented defconfig of NAME, every symbol, on stdout or into -o FILE")
p.add_argument("name")
p.add_argument("fragments", nargs="*")
+ p.add_argument("-o", dest="output_listing", help="write it here (safe for the file it is made from, as `>` is not)")
p.set_defaults(fn=cmd_listing)
p = sub.add_parser("complete", parents=[common], help="a defconfig must name every symbol")
p.add_argument("name")
p.set_defaults(fn=cmd_complete)
+ p = sub.add_parser("kernel", parents=[common], help="put the .config's choice of drivers into the kernel tree (make kernel runs it)")
+ p.add_argument("--tree", help="the kernel tree (default: $XNU_SRC, else xnu-src/xnu-8796.121.2)")
+ p.set_defaults(fn=cmd_kernel)
+ sub.add_parser("external-files", parents=[common], help="the driver files of SoC and device repositories, and their place in the tree").set_defaults(fn=cmd_external)
p = sub.add_parser("help", parents=[common], help="what a symbol means")
p.add_argument("symbol")
p.set_defaults(fn=cmd_help)
@@ -617,6 +1040,10 @@ def main():
a.config = os.path.abspath(getattr(a, "config", os.path.join(a.root, ".config")))
if getattr(a, "output", None) is None:
a.output = a.config
+ if DRIVERS_ERROR:
+ # a conf file that does not read leaves the drivers unknown, and every answer about a configuration would be wrong
+ print("hakios-config: %s" % DRIVERS_ERROR, file=sys.stderr)
+ sys.exit(1)
try:
sys.exit(a.fn(a))
except ConfigError as e:
diff --git a/tools/hakios-device-test.py b/tools/hakios-device-test.py
new file mode 100755
index 0000000..b27bd69
--- /dev/null
+++ b/tools/hakios-device-test.py
@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""tools/hakios-device.py and the layers of tools/hakios-config.py: a common repository, a SoC's, a device's with a driver of its own.
+
+Everything happens in a copy made for the test (the tools, configs/, the drivers' conf files, the SoC and device repositories):
+ - a device repository's defconfig is found as if it were in configs/; the same name in two repositories is refused
+ - its driver (devices/<name>/drivers/<sub>/conf) is a CONFIG_HAKIOS_ symbol like the common ones, goes into the kernel tree's
+ conf/files `optional`, and is listed by external-files for apply.sh, sync-drivers.sh and export.sh
+ - a device repository cannot declare `standard` files; a driver naming a file that is not there is a problem of `check`
+ - `new` makes a device that `check` passes, with the phone drivers left out but the SoC's
+ - the real tree's devices and SoCs hold together
+"""
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+ROOT = os.path.dirname(HERE)
+failures = []
+
+
+def check(label, ok, detail=""):
+ print("%s %s" % ("ok " if ok else "FAIL", label))
+ if not ok:
+ failures.append(label)
+ if detail:
+ print(" " + str(detail).strip().replace("\n", "\n ")[:800])
+
+
+def tool(root, name, *args):
+ return subprocess.run([sys.executable, os.path.join(root, "tools", name), *args], capture_output=True, text=True, cwd=root)
+
+
+work = tempfile.mkdtemp(prefix="hakios-device-test-")
+try:
+ root = os.path.join(work, "root")
+ os.makedirs(os.path.join(root, "tools"))
+ for t in ("hakios-config.py", "hakios-device.py", "boot-args.py", "kernel-version.py"):
+ shutil.copy(os.path.join(HERE, t), os.path.join(root, "tools", t))
+ shutil.copytree(os.path.join(ROOT, "configs"), os.path.join(root, "configs"))
+ shutil.copytree(os.path.join(ROOT, "socs"), os.path.join(root, "socs"))
+ for sub in os.listdir(os.path.join(ROOT, "drivers")):
+ if os.path.isfile(os.path.join(ROOT, "drivers", sub, "conf")):
+ os.makedirs(os.path.join(root, "drivers", sub))
+ shutil.copy(os.path.join(ROOT, "drivers", sub, "conf"), os.path.join(root, "drivers", sub, "conf"))
+ shutil.copytree(os.path.join(ROOT, "devices", "redwood", "configs"), os.path.join(root, "devices", "redwood", "configs"))
+ shutil.copy(os.path.join(ROOT, "devices", "redwood", "device.conf"), os.path.join(root, "devices", "redwood"))
+ open(os.path.join(root, "devices", "redwood", "pull-firmware.sh"), "w").close()
+ shutil.copy(os.path.join(ROOT, "devices", "manifest.conf"), os.path.join(root, "devices"))
+
+ r = tool(root, "hakios-device.py", "new", "fakephone", "--soc", "sc7280", "--title", "Fake Phone")
+ check("new: a device repository that check passes", r.returncode == 0 and "all hold together" in r.stdout, r.stdout + r.stderr)
+ conf = open(os.path.join(root, "devices", "fakephone", "configs", "fakephone.config")).read()
+ check("new: the phone drivers left out, the SoC's kept, QEMU's untouched",
+ "# CONFIG_HAKIOS_GOODIX is not set" in conf and "HAKIOS_THERMAL" not in conf and "HAKIOS_VIRTIO" not in conf, conf)
+ r = tool(root, "hakios-device.py", "new", "fakephone", "--soc", "sc7280", "--title", "x")
+ check("new: refuses a device that exists", r.returncode != 0 and "already exists" in r.stderr, r.stderr)
+ r = tool(root, "hakios-device.py", "new", "other", "--soc", "nosuchsoc", "--title", "x")
+ check("new: refuses a SoC with no repository", r.returncode != 0 and "no socs/nosuchsoc" in r.stderr, r.stderr)
+
+ # a driver of the device's own
+ d = os.path.join(root, "devices", "fakephone", "drivers", "input")
+ os.makedirs(d)
+ with open(os.path.join(d, "conf"), "w") as f:
+ f.write("driver FAKETOUCH\n\tfile bsd/dev/hakios.faketouch.c\n\thelp the fake phone's touch controller\n")
+ open(os.path.join(d, "hakios.faketouch.c"), "w").write("/* a touch driver */\n")
+ with open(os.path.join(root, "devices", "fakephone", "configs", "fakephone.config"), "a") as f:
+ f.write("CONFIG_HAKIOS_FAKETOUCH=y\n")
+ r = tool(root, "hakios-config.py", "help", "HAKIOS_FAKETOUCH")
+ check("a device's driver is a symbol like the common ones", r.returncode == 0 and "devices/fakephone/drivers/input/conf" in r.stdout, r.stdout + r.stderr)
+ r = tool(root, "hakios-config.py", "external-files")
+ check("external-files: its file, and where it goes in the tree",
+ r.stdout.strip() == "%s\tbsd/dev/hakios.faketouch.c" % os.path.join(d, "hakios.faketouch.c"), r.stdout + r.stderr)
+ r = tool(root, "hakios-config.py", "defconfig", "fakephone")
+ check("make fakephone_defconfig: found in the device's repository, the driver built", r.returncode == 0 and
+ "CONFIG_HAKIOS_FAKETOUCH=y" in open(os.path.join(root, ".config")).read(), r.stdout + r.stderr)
+ tree = os.path.join(work, "tree")
+ for sub in ("bsd/conf", "iokit/conf", "config", "bsd/dev"):
+ os.makedirs(os.path.join(tree, sub))
+ open(os.path.join(tree, "bsd/conf/files"), "w").write("bsd/dev/a.c standard\nbsd/dev/hakios.input.c standard\n")
+ open(os.path.join(tree, "iokit/conf/files"), "w").write("iokit/Kernel/hakios.gpu.cpp optional iokitcpp\n")
+ r = tool(root, "hakios-config.py", "kernel", "--tree", tree)
+ files = open(os.path.join(tree, "bsd/conf/files")).read()
+ check("kernel: the device's driver in conf/files and in the choice", r.returncode == 0 and
+ "bsd/dev/hakios.faketouch.c" in files and "optional hakios_faketouch" in files and
+ " hakios_faketouch " in open(os.path.join(tree, "config/MASTER.hakios")).read(), r.stdout + r.stderr + files)
+ r = tool(root, "hakios-device.py", "check", "fakephone")
+ check("check: the device with its driver holds together", r.returncode == 0, r.stdout + r.stderr)
+ os.remove(os.path.join(d, "hakios.faketouch.c"))
+ r = tool(root, "hakios-device.py", "check", "fakephone")
+ check("check: a driver naming a file that is not there is a problem", r.returncode != 0 and "hakios.faketouch.c" in r.stdout, r.stdout)
+ with open(os.path.join(d, "conf"), "a") as f:
+ f.write("standard bsd/dev/hakios.everyone.c\n")
+ r = tool(root, "hakios-config.py", "list")
+ check("a device repository cannot declare `standard` files", "a SoC or device repository has drivers, not `standard`" in r.stdout + r.stderr,
+ r.stdout + r.stderr)
+ os.remove(os.path.join(d, "conf"))
+ shutil.copy(os.path.join(root, "socs", "sc7280", "configs", "sc7280.config"),
+ os.path.join(root, "devices", "fakephone", "configs", "sc7280.config"))
+ r = tool(root, "hakios-config.py", "defconfig", "fakephone")
+ check("the same configuration name in two repositories is refused", r.returncode != 0 and "more than one repository" in r.stderr, r.stderr)
+
+ # the real tree
+ r = tool(ROOT, "hakios-device.py", "check")
+ check("the devices and SoCs of this tree hold together", r.returncode == 0, r.stdout + r.stderr)
+ r = tool(ROOT, "hakios-device.py", "list")
+ check("list names redwood, qemu and sc7280", all(n in r.stdout for n in ("redwood", "qemu", "sc7280")), r.stdout)
+finally:
+ shutil.rmtree(work, ignore_errors=True)
+
+if failures:
+ sys.exit("hakios-device-test: %d FAILED" % len(failures))
+print("hakios-device-test: all passed")
diff --git a/tools/hakios-device.py b/tools/hakios-device.py
new file mode 100755
index 0000000..5a66816
--- /dev/null
+++ b/tools/hakios-device.py
@@ -0,0 +1,422 @@
+#!/usr/bin/env python3
+"""HakiOS device and SoC repositories: the common repository (this one), a repository per SoC family, one per device.
+
+The way Android puts a phone's tree together (device/<vendor>/<name>, a <soc>-common, a manifest that names them) and the way XNU
+ports keep a board apart from the kernel: what is true of every device lives here (the kernel, the loader, the drivers, the tools);
+what is true of a SoC lives in socs/<soc>/; what is true of one device lives in devices/<name>/. Each of those two is a directory of
+the same shape that may be its own git repository:
+
+ devices/<name>/device.conf what the device is, and how far each part of it works (the device's page is made from it)
+ devices/<name>/configs/ <name>_defconfig (#include common_defconfig, the SoC's fragment, <name>.config) and fragments
+ devices/<name>/drivers/<sub>/conf drivers of its own, if it has any, in the format of drivers/<sub>/conf (docs/drivers-config.md)
+ socs/<soc>/soc.conf, configs/<soc>.config, drivers/... the same for a SoC family
+
+devices/manifest.conf names every one: `path` for one kept in this tree, `repository` and `revision` for one that is its own
+repository, which `sync` clones into place at that revision.
+
+ tools/hakios-device.py list the devices and SoCs, where each is, how far each part works
+ tools/hakios-device.py check [NAME...] a device or SoC repository holds together (CI runs it on every one)
+ tools/hakios-device.py new NAME --soc SOC ... a new device repository, with every phone driver left out to begin with
+ tools/hakios-device.py sync [NAME...] clone or update the repositories the manifest names, at their revisions
+ tools/hakios-device.py lock NAME write the revision checked out into the manifest
+ tools/hakios-device.py split NAME DIR a device kept in this tree as a git repository of its own, with its history
+
+docs/porting/repositories.md is the guide.
+"""
+import argparse
+import importlib.util
+import os
+import re
+import shutil
+import subprocess
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+ROOT = os.path.dirname(HERE)
+STATES = ("works", "partial", "missing")
+AREAS = ("display", "touch", "buttons", "cpu", "gpu", "storage", "audio", "battery", "haptic", "camera", "torch", "wifi",
+ "bluetooth", "cellular", "network", "thermal", "usb", "sensors")
+DEVICE_KEYS = {"title", "vendor", "soc", "defconfig", "firmware", "maintainer", "status", "repository", "revision", "path"}
+SOC_KEYS = {"title", "vendor", "cores", "gpu", "maintainer", "repository", "revision", "path"}
+
+
+class Problem(Exception):
+ pass
+
+
+def config_tool():
+ spec = importlib.util.spec_from_file_location("hakios_config", os.path.join(HERE, "hakios-config.py"))
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+def read_blocks(path, kinds, keys):
+ """[(kind, name, {key: [values]}, line)] of a file of blocks: `<kind> <name>` and indented `<key> <value>` lines under it."""
+ blocks, block = [], None
+ shown = os.path.relpath(path, ROOT)
+ for n, raw in enumerate(open(path, encoding="utf-8"), 1):
+ line = raw.split("#", 1)[0].rstrip()
+ if not line.strip():
+ continue
+ words = line.split()
+ if not raw[0].isspace():
+ if words[0] not in kinds or len(words) != 2 or not re.fullmatch(r"[a-z0-9][a-z0-9_-]*", words[1]):
+ raise Problem("%s:%d: want `%s NAME` (lowercase), got %r" % (shown, n, " NAME` or `".join(kinds), line.strip()))
+ block = (words[0], words[1], {}, n)
+ blocks.append(block)
+ continue
+ if block is None:
+ raise Problem("%s:%d: an indented line before any block" % (shown, n))
+ key, value = words[0], line.strip()[len(words[0]):].strip()
+ allowed = keys[block[0]]
+ if key not in allowed:
+ raise Problem("%s:%d: %s does not take `%s` (it takes: %s)" % (shown, n, block[0], key, ", ".join(sorted(allowed))))
+ block[2].setdefault(key, []).append((value, n))
+ return blocks
+
+
+def one(fields, key, default=None):
+ values = fields.get(key)
+ return values[-1][0] if values else default
+
+
+def manifest():
+ path = os.path.join(ROOT, "devices", "manifest.conf")
+ if not os.path.isfile(path):
+ return []
+ return read_blocks(path, ("device", "soc"), {"device": DEVICE_KEYS, "soc": SOC_KEYS})
+
+
+def home(kind, name):
+ return os.path.join(ROOT, "devices" if kind == "device" else "socs", name)
+
+
+def describe(kind, name):
+ """The block of devices/<name>/device.conf or socs/<name>/soc.conf, or None if it is not checked out."""
+ path = os.path.join(home(kind, name), "device.conf" if kind == "device" else "soc.conf")
+ if not os.path.isfile(path):
+ return None
+ blocks = read_blocks(path, (kind,), {"device": DEVICE_KEYS, "soc": SOC_KEYS})
+ if len(blocks) != 1 or blocks[0][1] != name:
+ raise Problem("%s: want one `%s %s` block" % (os.path.relpath(path, ROOT), kind, name))
+ return blocks[0][2]
+
+
+def present():
+ """[(kind, name)] of every device and SoC checked out, whether or not the manifest names it."""
+ out = []
+ for kind, top, marker in (("soc", "socs", "soc.conf"), ("device", "devices", "device.conf")):
+ base = os.path.join(ROOT, top)
+ for name in sorted(os.listdir(base)) if os.path.isdir(base) else []:
+ if os.path.isfile(os.path.join(base, name, marker)):
+ out.append((kind, name))
+ return out
+
+
+def statuses(fields):
+ """[(area, state, note)] of a device's `status` lines, checked."""
+ out = []
+ for value, n in fields.get("status", []):
+ parts = value.split(None, 2)
+ if len(parts) < 2 or parts[0] not in AREAS or parts[1] not in STATES:
+ raise Problem("line %d: want `status <area> works|partial|missing <note>`, the area one of %s (got %r)" %
+ (n, ", ".join(AREAS), value))
+ out.append((parts[0], parts[1], parts[2] if len(parts) > 2 else ""))
+ return out
+
+
+# ---- commands ----------------------------------------------------------------------------------------------------
+
+def cmd_list(_a):
+ named = {(k, n): f for k, n, f, _l in manifest()}
+ every = sorted(set(named) | set(present()), key=lambda x: (x[0] != "soc", x[1]))
+ for kind, name in every:
+ fields = describe(kind, name)
+ where = one(named.get((kind, name), {}), "repository") or one(named.get((kind, name), {}), "path") or "(not in the manifest)"
+ if fields is None:
+ print("%-6s %-10s NOT CHECKED OUT (tools/hakios-device.py sync %s) %s" % (kind, name, name, where))
+ continue
+ line = "%-6s %-10s %-44s %s" % (kind, name, one(fields, "title", "?")[:44], where)
+ if kind == "device":
+ counts = {s: 0 for s in STATES}
+ for _area, state, _note in statuses(fields):
+ counts[state] += 1
+ line += " [%d works, %d partial, %d missing]" % (counts["works"], counts["partial"], counts["missing"])
+ print(line)
+ return 0
+
+
+def check_one(kind, name, hc):
+ problems = []
+ try:
+ fields = describe(kind, name)
+ except Problem as e:
+ return [str(e)]
+ if fields is None:
+ return ["%s %s is not checked out" % (kind, name)]
+ top = home(kind, name)
+ shown = os.path.relpath(top, ROOT)
+ if not one(fields, "title"):
+ problems.append("%s: no title" % shown)
+ if kind == "device":
+ try:
+ areas = statuses(fields)
+ except Problem as e:
+ problems.append("%s/device.conf: %s" % (shown, e))
+ areas = []
+ if len({a for a, _s, _n in areas}) != len(areas):
+ problems.append("%s/device.conf: an area has two status lines" % shown)
+ soc = one(fields, "soc")
+ if soc is None:
+ problems.append("%s/device.conf: no soc (`none` for a machine with no SoC repository)" % shown)
+ elif soc != "none" and not os.path.isfile(os.path.join(ROOT, "socs", soc, "soc.conf")):
+ problems.append("%s/device.conf: soc %s, and there is no socs/%s/soc.conf (tools/hakios-device.py sync %s)" % (shown, soc, soc, soc))
+ defconfig = one(fields, "defconfig")
+ path = os.path.join(top, "configs", defconfig or "")
+ if not defconfig or not os.path.isfile(path):
+ problems.append("%s/device.conf: defconfig %s is not in %s/configs/" % (shown, defconfig, shown))
+ else:
+ includes = [l.split()[1] for l in open(path, encoding="utf-8") if l.startswith("#include ")]
+ if "common_defconfig" not in includes:
+ problems.append("%s/configs/%s does not #include common_defconfig: a device is the common kernel plus its own" % (shown, defconfig))
+ if soc not in (None, "none") and soc + ".config" not in includes:
+ problems.append("%s/configs/%s does not #include %s.config (its SoC's facts)" % (shown, defconfig, soc))
+ out = subprocess.run([sys.executable, os.path.join(HERE, "hakios-config.py"), "defconfig", defconfig, "-o", os.devnull],
+ capture_output=True, text=True, cwd=ROOT)
+ for l in (out.stdout + out.stderr).splitlines():
+ if "PROBLEM" in l or out.returncode != 0 and l.startswith("hakios-config:") and "made from" not in l and "characters" not in l:
+ problems.append("%s/configs/%s: %s" % (shown, defconfig, l.replace("hakios-config: ", "")))
+ firmware = one(fields, "firmware")
+ if firmware and not os.path.isfile(os.path.join(top, firmware)):
+ problems.append("%s/device.conf: firmware %s is not there" % (shown, firmware))
+ else:
+ fragment = os.path.join(top, "configs", name + ".config")
+ if not os.path.isfile(fragment):
+ problems.append("%s: no configs/%s.config, the fragment a device with this SoC includes" % (shown, name))
+ for d in hc.DRIVERS:
+ if d.origin and os.path.abspath(d.origin) == os.path.abspath(top):
+ for f, _tags in d.files:
+ if not os.path.isfile(d.source(f)):
+ problems.append("%s: the driver %s names %s, which is not there" % (d.where, d.name, os.path.relpath(d.source(f), ROOT)))
+ return problems
+
+
+def cmd_check(a):
+ hc = config_tool()
+ if hc.DRIVERS_ERROR:
+ print("hakios-device: " + hc.DRIVERS_ERROR)
+ return 1
+ every = present()
+ wanted = [(k, n) for k, n in every if not a.names or n in a.names]
+ missing = [n for n in a.names if n not in {x[1] for x in every}]
+ problems = ["%s: not checked out here" % n for n in missing]
+ for kind, name in wanted:
+ problems += check_one(kind, name, hc)
+ names = {}
+ for kind, name in every:
+ if name in names:
+ problems.append("%s is both a %s and a %s: a configuration name would be ambiguous" % (name, names[name], kind))
+ names[name] = kind
+ for p in problems:
+ print("hakios-device: " + p)
+ print("hakios-device: %d repositories checked (%s)%s" % (len(wanted), ", ".join(n for _k, n in wanted),
+ ", %d problem(s)" % len(problems) if problems else ", all hold together"))
+ return 1 if problems else 0
+
+
+NEW_README = """# {title} ({name})
+
+A HakiOS device repository: what is true of this device and of no other. The kernel, the loader, the drivers and the tools are
+the common repository's; the {soc} family's facts are `socs/{soc}/`'s. How the three are put together:
+[docs/porting/repositories.md](https://github.com/shimoku74/hakios/blob/main/docs/porting/repositories.md).
+
+| File | What |
+|---|---|
+| `device.conf` | what the device is, and how far each part of it works: its page in the documentation is made from it |
+| `configs/{name}_defconfig` | the common kernel, the SoC's fragment, this device's: `make {name}_defconfig` |
+| `configs/{name}.config` | what is this device's own: the drivers built in, the arguments it needs |
+| `drivers/` | drivers of its own, if it needs any (`drivers/<subsystem>/conf`, as in the common repository) |
+
+Every phone driver of the common repository is left out to begin with: their addresses and pins are the phone they were written
+for. Put one back in `configs/{name}.config` when it has been made to work here, and say so in `device.conf`.
+
+Check with `tools/hakios-device.py check {name}`.
+"""
+
+
+def cmd_new(a):
+ name = a.name
+ if not re.fullmatch(r"[a-z0-9][a-z0-9_-]*", name):
+ raise Problem("a device's name is its codename, lowercase: %s" % name)
+ top = home("device", name)
+ if os.path.exists(top):
+ raise Problem("devices/%s already exists" % name)
+ if a.fdt or a.adb:
+ # the phone's own device tree first: tools/new-device.py makes the directory with soc.args and its README
+ out = subprocess.run([sys.executable, os.path.join(HERE, "new-device.py"), name] + (["--fdt", a.fdt] if a.fdt else ["--adb"]),
+ cwd=ROOT, capture_output=True, text=True)
+ print(out.stdout.rstrip())
+ if out.returncode != 0:
+ raise Problem("tools/new-device.py: %s" % (out.stderr.strip() or "failed"))
+ if a.soc != "none" and not os.path.isfile(os.path.join(ROOT, "socs", a.soc, "soc.conf")):
+ raise Problem("no socs/%s/soc.conf: make the SoC's repository first, or sync it (known: %s)" %
+ (a.soc, ", ".join(n for k, n in present() if k == "soc") or "none"))
+ hc = config_tool()
+ # what a new device begins without: every driver written for one machine (not QEMU's), but the ones its SoC's fragment builds
+ soc_has = hc.parse(hc.find_config(ROOT, a.soc + ".config"))[0] if a.soc != "none" else {}
+ left_out = [d.symbol for d in hc.DRIVERS if not d.name.startswith("VIRTIO_") and soc_has.get(d.symbol) != "y"]
+ os.makedirs(os.path.join(top, "configs"), exist_ok=True)
+ with open(os.path.join(top, "device.conf"), "w", encoding="utf-8") as f:
+ f.write("# devices/%s/device.conf: what this device repository is (docs/porting/repositories.md has every word).\n\n"
+ "device %s\n\ttitle %s\n\tvendor %s\n\tsoc %s\n\tdefconfig %s_defconfig\n"
+ "\tmaintainer %s\n\tstatus display partial UEFI's framebuffer, through the loader (to be checked)\n" %
+ (name, name, a.title, a.vendor, a.soc, name, a.maintainer))
+ with open(os.path.join(top, "configs", name + "_defconfig"), "w", encoding="utf-8") as f:
+ f.write("# HakiOS defconfig for the %s (%s): the common kernel, %s, and this device's own.\n#include common_defconfig\n%s"
+ "#include %s.config\n" % (a.title, name, "the %s family's facts" % a.soc if a.soc != "none" else "no SoC repository",
+ "#include %s.config\n" % a.soc if a.soc != "none" else "", name))
+ with open(os.path.join(top, "configs", name + ".config"), "w", encoding="utf-8") as f:
+ f.write("# HakiOS fragment: the %s (%s) -- what is true of this device and of no other.\n" % (a.title, name))
+ f.write("# Every phone driver is left out until it has been made to work here; the arguments only those drivers read go too.\n")
+ f.write('CONFIG_DEVICE="%s"\n' % name)
+ for sym in left_out:
+ f.write("# CONFIG_%s is not set\n" % sym)
+ common = hc.overlay({}, [hc.find_config(ROOT, "common_defconfig")] + ([hc.find_config(ROOT, a.soc + ".config")] if soc_has else []))
+ problems, _ = hc.check(dict(common, **{s: "n" for s in left_out}))
+ for p in problems:
+ m = re.match(r"CONFIG_([A-Z0-9_]+) gives ", p)
+ if m:
+ f.write("# CONFIG_%s is not set\n" % m.group(1))
+ f.write('# CONFIG_FIRMWARE is "device" in the common kernel: say "none" here until this device\'s firmware is pulled\n')
+ readme = os.path.join(top, "README.md")
+ if os.path.isfile(readme): # new-device.py's, about the device tree: the repository's part goes after it
+ with open(readme, "a", encoding="utf-8") as f:
+ f.write("\n## The repository\n\n" + NEW_README.format(title=a.title, name=name, soc=a.soc).split("\n", 2)[2])
+ else:
+ with open(readme, "w", encoding="utf-8") as f:
+ f.write(NEW_README.format(title=a.title, name=name, soc=a.soc))
+ print("hakios-device: devices/%s made: device.conf, configs/%s_defconfig, configs/%s.config, README.md" % (name, name, name))
+ print("hakios-device: %d phone drivers left out to begin with; `make %s_defconfig && make config` shows what is built" % (len(left_out), name))
+ print("hakios-device: next: docs/porting/index.md, step by step; tools/new-device.py reads the phone's own device tree")
+ return cmd_check(argparse.Namespace(names=[name]))
+
+
+def git(*args, cwd=None):
+ out = subprocess.run(["git", *args], cwd=cwd or ROOT, capture_output=True, text=True)
+ if out.returncode != 0:
+ raise Problem("git %s: %s" % (" ".join(args), out.stderr.strip()))
+ return out.stdout.strip()
+
+
+def cmd_sync(a):
+ entries = [(k, n, f) for k, n, f, _l in manifest() if not a.names or n in a.names]
+ done = 0
+ for kind, name, fields in entries:
+ repository, revision = one(fields, "repository"), one(fields, "revision")
+ if not repository:
+ continue # kept in this tree (`path`)
+ top = home(kind, name)
+ if not os.path.isdir(os.path.join(top, ".git")):
+ if os.path.exists(top):
+ raise Problem("%s exists and is not a clone of %s: move it away first" % (os.path.relpath(top, ROOT), repository))
+ print("hakios-device: %s: cloning %s" % (name, repository))
+ git("clone", "-q", repository, top)
+ else:
+ git("fetch", "-q", "origin", cwd=top)
+ if revision:
+ git("checkout", "-q", revision, cwd=top)
+ print("hakios-device: %s %s at %s" % (kind, name, git("rev-parse", "--short=12", "HEAD", cwd=top)))
+ done += 1
+ print("hakios-device: %d repositories synced%s" % (done, "" if done else " (every one the manifest names is kept in this tree)"))
+ return 0
+
+
+def cmd_lock(a):
+ path = os.path.join(ROOT, "devices", "manifest.conf")
+ lines = open(path, encoding="utf-8").read().split("\n")
+ for kind, name, fields, start in manifest():
+ if name != a.name:
+ continue
+ if not one(fields, "repository"):
+ raise Problem("%s is kept in this tree: it has no revision to lock" % name)
+ sha = git("rev-parse", "HEAD", cwd=home(kind, name))
+ if "revision" in fields:
+ n = fields["revision"][-1][1] - 1
+ lines[n] = re.sub(r"revision\s+\S+", "revision " + sha, lines[n])
+ else:
+ lines.insert(start, "\trevision " + sha)
+ open(path, "w", encoding="utf-8", newline="\n").write("\n".join(lines))
+ print("hakios-device: %s locked at %s" % (name, sha[:12]))
+ return 0
+ raise Problem("no %s in devices/manifest.conf" % a.name)
+
+
+def cmd_split(a):
+ kinds = {n: k for k, n in present()}
+ if a.name not in kinds:
+ raise Problem("no device or SoC %s checked out" % a.name)
+ prefix = os.path.relpath(home(kinds[a.name], a.name), ROOT)
+ if os.path.exists(a.dir):
+ raise Problem("%s already exists" % a.dir)
+ branch = "split/" + a.name
+ try:
+ sha = git("subtree", "split", "-q", "--prefix=" + prefix, "-b", branch)
+ except Problem:
+ sha = None
+ if sha:
+ git("clone", "-q", "--branch", branch, ROOT, a.dir)
+ git("branch", "-D", branch)
+ git("remote", "remove", "origin", cwd=a.dir)
+ how = "with the history of %s" % prefix
+ else: # no git subtree here: the files as they are, in one first commit
+ shutil.copytree(os.path.join(ROOT, prefix), a.dir)
+ git("init", "-q", cwd=a.dir)
+ git("add", "-A", cwd=a.dir)
+ git("commit", "-q", "-m", "%s: the device repository, split from the common one" % a.name, cwd=a.dir)
+ how = "in one commit (git subtree is not installed: the history stays in the common repository)"
+ print("hakios-device: %s is a repository of its own in %s, %s" % (prefix, a.dir, how))
+ print("hakios-device: to publish it: make an empty repository (e.g. hakios-%s-%s), then\n"
+ " git -C %s remote add origin <its URL> && git -C %s push -u origin HEAD:main\n"
+ "and in devices/manifest.conf replace `path %s` by `repository <its URL>`, then tools/hakios-device.py lock %s" %
+ (kinds[a.name], a.name, a.dir, a.dir, prefix, a.name))
+ return 0
+
+
+def main():
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ sub = ap.add_subparsers(dest="command", required=True)
+ sub.add_parser("list", help="the devices and SoCs").set_defaults(fn=cmd_list)
+ p = sub.add_parser("check", help="a device or SoC repository holds together")
+ p.add_argument("names", nargs="*")
+ p.set_defaults(fn=cmd_check)
+ p = sub.add_parser("new", help="a new device repository")
+ p.add_argument("name")
+ p.add_argument("--soc", required=True, help="its SoC family (socs/<soc>/), or none")
+ p.add_argument("--title", required=True, help='what it is called ("POCO X5 Pro 5G")')
+ p.add_argument("--vendor", default="?")
+ p.add_argument("--maintainer", default="?")
+ tree = p.add_mutually_exclusive_group()
+ tree.add_argument("--fdt", help="the phone's own device tree (adb pull /sys/firmware/fdt): tools/new-device.py reads it first")
+ tree.add_argument("--adb", action="store_true", help="... pulled from the phone on adb now")
+ p.set_defaults(fn=cmd_new)
+ p = sub.add_parser("sync", help="clone or update the repositories the manifest names")
+ p.add_argument("names", nargs="*")
+ p.set_defaults(fn=cmd_sync)
+ p = sub.add_parser("lock", help="write the revision checked out into the manifest")
+ p.add_argument("name")
+ p.set_defaults(fn=cmd_lock)
+ p = sub.add_parser("split", help="a device or SoC kept in this tree as a repository of its own")
+ p.add_argument("name")
+ p.add_argument("dir")
+ p.set_defaults(fn=cmd_split)
+ a = ap.parse_args()
+ try:
+ sys.exit(a.fn(a))
+ except Problem as e:
+ print("hakios-device: %s" % e, file=sys.stderr)
+ sys.exit(1)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/tools/make-kernel.sh b/tools/make-kernel.sh
index dbe5296..21828d3 100755
--- a/tools/make-kernel.sh
+++ b/tools/make-kernel.sh
@@ -19,7 +19,7 @@ KERNEL=${KERNEL:-xnu-src/xnu-8796.121.2/BUILD/obj/DEVELOPMENT_ARM64_BCM2837/mach
# stand above them (config_all and the recursion into config/, and the top-level `all`)
unexpected_failures() {
grep -E '^make(\[[0-9]+\])?: \*\*\* ' "$1" |
- grep -vE '\.symbolset\]|check_all_exports|config_all|_recurse_into_config|\[Makefile:[0-9]+: all\]'
+ grep -vE '\.symbolset\]|check_all_exports|config_all|_recurse_into_config|\[Makefile:[0-9]+: all\]|^make: \*\*\* \[all\] Error'
}
judge() { # judge LOG: 0 if the kernel is built and only the symbol-set steps failed
@@ -39,8 +39,12 @@ if [ "$1" = --judge ]; then
exit
fi
-# what was edited in drivers/ goes into the kernel tree first (only what is newer than the tree's copy)
-[ ! -d xnu-src/xnu-8796.121.2 ] || xnu/sync-drivers.sh xnu-src/xnu-8796.121.2 || exit 1
+# what was edited in drivers/ goes into the kernel tree first (only what is newer than the tree's copy), and then the
+# drivers the .config builds (CONFIG_HAKIOS_*; every driver when there is no .config): docs/drivers-config.md
+if [ -d xnu-src/xnu-8796.121.2 ]; then
+ xnu/sync-drivers.sh xnu-src/xnu-8796.121.2 || exit 1
+ python3 tools/hakios-config.py kernel --tree xnu-src/xnu-8796.121.2 || exit 1
+fi
log=${KERNEL_LOG:-xnu-build.log}
./xnu-build.sh -k "$@" 2>&1 | tee "$log"
status=${PIPESTATUS[0]}
diff --git a/tools/new-device.py b/tools/new-device.py
index 7e742d7..e2cbabf 100755
--- a/tools/new-device.py
+++ b/tools/new-device.py
@@ -206,6 +206,11 @@ The kernel's settings are layered the way an Android kernel's are: the common ke
Then `make {name}_defconfig`. Turn on only what this phone has been shown to do; `tools/hakios-config.py check` says what the
choice needs.
+The drivers are part of the configuration too (`docs/drivers-config.md`): every one is built unless a configuration leaves it out,
+and the addresses, pins and rails in each are the reference phone's. Leave out in `configs/{name}.config` what has not been
+ported to this phone yet (`# CONFIG_HAKIOS_GOODIX is not set`, ...; `configs/qemu_defconfig` leaves out all of them), and put
+each one back when it has been made to work here. `tools/hakios-config.py show` lists what is built in.
+
## Firmware
Pulled from your own phone, never committed: `devices/{reference}/pull-firmware.sh`, or
diff --git a/tools/provenance.allow b/tools/provenance.allow
index 12c683f..85d930c 100644
--- a/tools/provenance.allow
+++ b/tools/provenance.allow
@@ -10,7 +10,7 @@
open prebuilt/mach.development.bcm2837 the kernel, built from Apple's open xnu-8796.121.2 plus xnu/hakios.patch and xnu/files: APSL-2.0, corresponding source here and at Apple
open prebuilt/loader.efi the boot loader, built from xnuloader/loader.c: MIT
open prebuilt/userland/* our programs and libraries, built from userland/src: MIT
-open devices/redwood/prebuilt/BootShim.bin built from the shim of Mu-Silicium with our change (devices/redwood/uefi/mu-silicium.patch): BSD-2-Clause-Patent
+open devices/redwood/prebuilt/BootShim.bin built from the shim of Mu-Silicium with our change (uefi/hakios.patch): BSD-2-Clause-Patent
# --- a description of the hardware ------------------------------------------------------------------------
pending devices/redwood/prebuilt/device-tree.dtb the phone's device tree, compiled from Linux sources that are GPL-2.0; confirm the headers, or have each user pull it from their own phone as tools/soc-args.py already does
diff --git a/uefi/BASE b/uefi/BASE
new file mode 100644
index 0000000..eacc726
--- /dev/null
+++ b/uefi/BASE
@@ -0,0 +1 @@
+e51cd877e31c8fbb322032dc4cb6715e83d25ad3
diff --git a/uefi/README.md b/uefi/README.md
new file mode 100644
index 0000000..e4b00e1
--- /dev/null
+++ b/uefi/README.md
@@ -0,0 +1,101 @@
+# HakiOS UEFI
+
+The UEFI firmware HakiOS phones start with: [Project Silicium's Mu-Silicium](https://github.com/Project-Silicium/Mu-Silicium)
+at a fixed commit, with HakiOS's changes on top, and the platform of each phone from its device repository.
+
+| What | Where |
+|---|---|
+| the Mu-Silicium commit it is made on | `BASE` |
+| HakiOS's changes to Silicium's files | `hakios.patch` |
+| HakiOS's new files (the XNU loader in the boot manager) | `files/` |
+| the pictures it shows | `branding/banner.py` makes them |
+| a phone's platform (memory map, drivers list, its device tree) | `devices/<name>/uefi/files/` in the device's repository |
+
+## What HakiOS changes
+
+| Part | Change |
+|---|---|
+| `BootShim/BootShim.S` | copies the `XNUP` container behind the UEFI image to `0xF0000000`, where the loader finds the kernel |
+| `BootManagerLib` | starts the XNU loader from that container (`XnuLoader.c`) instead of showing a boot menu |
+| `BootLogo.bmp`, `NoBootOS.bmp`, `MassStorage.bmp` | HakiOS's emblem and name in place of Silicium's: what the phone shows while it starts is ours, every time |
+| `PcdFirmwareVendor` | `HakiOS` (what the firmware and its SMBIOS tables say they are) |
+| `Sec.c` | the first log line: `HakiOS UEFI (Mu-Silicium) for <maker> <model>` |
+
+Mu-Silicium's own code keeps its licence and its authors' notices; this is a fork of it in the open, as its licence allows.
+
+## The pictures
+
+```sh
+python3 uefi/branding/banner.py /tmp/banner # BootLogo.bmp, NoBootOS.bmp, MassStorage.bmp
+```
+
+They are drawn from a few shapes and a 5x7 pixel font (the emblem is the website's logo, the wordmark HAKI in paper and OS in red),
+as 8-bit BMPs with a 256-colour palette, the format and sizes Silicium's are (300x300, 300x300, 500x500). Nothing to install; change
+the text or the colours in the file and run `uefi/apply.sh` again.
+
+## Make the tree
+
+```sh
+uefi/apply.sh # Mu-Silicium/ at the top: BASE, hakios.patch, files/, the pictures, every device's platform
+uefi/apply.sh redwood # ... with one device's platform only
+uefi/export.sh # the reverse, after changing something in Mu-Silicium/
+```
+
+## The vendor's drivers are not in the repository
+
+A phone's UEFI is made of open code (Project Mu, EDK2) and of drivers that Qualcomm and Xiaomi wrote for
+that phone: display, storage, USB, secure boot and more. They are proprietary and have not been
+licensed for redistribution, so a device repository carries neither them (`devices/<name>/uefi/files/Binaries/<name>/*`) nor
+the UEFI image built with them (`prebuilt/SILICIUM_UEFI.fd`). `tools/provenance-check.py` fails the
+build if they come back; it runs on every push, and `tools/provenance.allow` says why each binary that
+*is* here may be.
+
+Without that image `mkxnuimg.py` stops with a message that points here. To get one, make both from
+**your own phone**:
+
+1. Get your phone's UEFI firmware: the vendor's `xbl` firmware, which is on the phone (with root, the
+ `xbl` partition) and in the vendor's firmware package for your model and region.
+ `devices/redwood/uefi/files/Binaries/redwood/README.md` records the version the port was made on (`OS1.0.3.0.UMSMIXM`):
+ another version may need other patches.
+2. Extract the drivers from it with [UEFIReader](https://github.com/WOA-Project/UEFIReader) into
+ `devices/<name>/uefi/files/Binaries/<name>/`. Its README says no more than what the tool is for ("generate .inf
+ payloads ... out of an existing UEFI volume", as of 2026-10-26); Mu-Silicium's documentation for a
+ device describes the layout it expects. **The authors of this repository have not repeated this
+ extraction since the drivers were taken out of the tree: if you do it, say what worked in an
+ issue.**
+3. Build as below. `mkxnuimg.py` then takes the image from `Mu-Silicium/`.
+
+What you extract is the vendor's, from your own device: keep it on your disk and never commit it.
+
+## Build
+
+Packages as in Mu-Silicium's `setup_env.sh` (Arch: `git base-devel lld nasm clang llvm
+aarch64-linux-gnu-gcc python python-pip python-virtualenv`).
+
+```sh
+uefi/apply.sh redwood # clones Mu-Silicium (with submodules, ~3 GB), HakiOS's changes, the redwood platform
+python3 -m venv venv && venv/bin/pip install -r Mu-Silicium/pip-requirements.txt
+cd Mu-Silicium
+source ../venv/bin/activate
+python3 build_uefi.py -d redwood -r RELEASE # -> Build/redwoodPkg/RELEASE_CLANGPDB/FV/SILICIUM_UEFI.fd
+```
+
+The `mu_nasm` dependency comes through NuGet and wants Mono; without Mono, point it at the
+system nasm:
+
+```sh
+D=Mu_Basecore/BaseTools/Bin/mu_nasm_extdep
+mkdir -p $D/Linux-x86-64
+echo 'version: 20016.1.1' > $D/extdep_state.yaml
+ln -s /usr/bin/nasm /usr/bin/ndisasm $D/Linux-x86-64/
+```
+
+After a build, `mkxnuimg.py` (called by `./xl enter`) takes the UEFI from `Mu-Silicium/`, and
+`tools/update-prebuilt.sh` refreshes `devices/redwood/prebuilt`. `uefi/export.sh`
+is the reverse: it saves the changes from `Mu-Silicium/` back.
+
+## What has been checked
+
+27 October 2026: `uefi/apply.sh`'s steps, run on a checkout of Mu-Silicium at `BASE`, give the same tree as the earlier redwood
+port, with the HakiOS pictures, vendor and log line in it. **The firmware has not been built or started with these changes yet**:
+the build needs the vendor's drivers of a phone (above). The pictures are in the format and sizes of Silicium's own.
diff --git a/uefi/apply.sh b/uefi/apply.sh
new file mode 100755
index 0000000..c70f0e6
--- /dev/null
+++ b/uefi/apply.sh
@@ -0,0 +1,34 @@
+#!/bin/bash
+# HakiOS's UEFI: Project Silicium's Mu-Silicium at the commit in BASE, with HakiOS's changes on top, and the platform of each
+# device that has one (devices/<name>/uefi/files/). The result is Mu-Silicium/ at the top of the repository, which mkxnuimg.py
+# and tools/update-prebuilt.sh take the image from.
+#
+# uefi/apply.sh [DEVICE...] default: every device with a devices/<name>/uefi/files/
+#
+# What HakiOS changes in Mu-Silicium (hakios.patch, files/, branding/):
+# BootShim.S copies the "XNUP" container behind the UEFI image to 0xF0000000, where the loader finds the kernel
+# BootManagerLib starts the XNU loader from that container (XnuLoader.c) instead of showing a boot menu
+# the banner BootLogo.bmp, NoBootOS.bmp and MassStorage.bmp are HakiOS's, made by branding/banner.py, in place of
+# Silicium's: the logo the phone shows while it starts is ours, always
+# the vendor the firmware says "HakiOS" (PcdFirmwareVendor, the SMBIOS tables) and its first log line is HakiOS's
+set -e
+HERE=$(cd "$(dirname "$(readlink -f "$0")")" && pwd)
+ROOT=$(dirname "$HERE")
+MU=${MU:-$ROOT/Mu-Silicium}
+[ -e "$MU" ] && { echo "uefi/apply.sh: $MU already exists (uefi/export.sh saves what is in it; move it away for a fresh one)"; exit 1; }
+git clone https://github.com/Project-Silicium/Mu-Silicium.git "$MU"
+git -C "$MU" checkout -q "$(cat "$HERE/BASE")"
+git -C "$MU" submodule update --init --recursive
+git -C "$MU" apply --whitespace=nowarn "$HERE/hakios.patch"
+cp -r "$HERE/files/." "$MU/"
+python3 "$HERE/branding/banner.py" "$MU/Silicon/Silicium/SiliciumPkg/Include/Resources"
+devices=("$@")
+if [ ${#devices[@]} -eq 0 ]; then
+ for d in "$ROOT"/devices/*/uefi/files; do [ -d "$d" ] && devices+=("$(basename "$(dirname "$(dirname "$d")")")"); done
+fi
+for d in "${devices[@]}"; do
+ [ -d "$ROOT/devices/$d/uefi/files" ] || { echo "uefi/apply.sh: devices/$d has no uefi/files/" >&2; exit 1; }
+ cp -r "$ROOT/devices/$d/uefi/files/." "$MU/"
+ echo "uefi/apply.sh: the platform of $d"
+done
+echo "uefi/apply.sh: done; build with: cd Mu-Silicium && python3 build_uefi.py -d <device> -r RELEASE (uefi/README.md)"
diff --git a/uefi/branding/banner.py b/uefi/branding/banner.py
new file mode 100755
index 0000000..ed41c3d
--- /dev/null
+++ b/uefi/branding/banner.py
@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""The pictures HakiOS's UEFI shows in place of Mu-Silicium's: the boot logo, the "no system to boot" screen and the USB mass
+storage screen. Made here from a few shapes and a 5x7 pixel font, with nothing to install, so that anyone can change the text
+or the colours and make them again.
+
+The files are what Mu-Silicium's SiliciumPkg/Include/Resources/ holds (Extra.fdf.inc puts them into the firmware volume):
+8-bit BMPs with a 256-colour palette, BootLogo.bmp and NoBootOS.bmp 300x300, MassStorage.bmp 500x500.
+
+usage: uefi/branding/banner.py OUTDIR (uefi/apply.sh runs it into the Mu-Silicium tree)
+"""
+import os
+import struct
+import sys
+
+INK, RED, PAPER, GREY = (0, 0, 0), (0xE8, 0x17, 0x0F), (0xEF, 0xE9, 0xE6), (0x8A, 0x84, 0x82)
+PALETTE = [INK, RED, PAPER, GREY] # indices 0..3; the rest of the 256 are black
+
+FONT = { # 5x7, one string per row, "#" is a pixel
+ "A": [" ### ", "# #", "# #", "#####", "# #", "# #", "# #"],
+ "B": ["#### ", "# #", "# #", "#### ", "# #", "# #", "#### "],
+ "D": ["#### ", "# #", "# #", "# #", "# #", "# #", "#### "],
+ "E": ["#####", "# ", "# ", "#### ", "# ", "# ", "#####"],
+ "F": ["#####", "# ", "# ", "#### ", "# ", "# ", "# "],
+ "G": [" ####", "# ", "# ", "# ##", "# #", "# #", " ### "],
+ "H": ["# #", "# #", "# #", "#####", "# #", "# #", "# #"],
+ "I": ["#####", " # ", " # ", " # ", " # ", " # ", "#####"],
+ "K": ["# #", "# # ", "# # ", "## ", "# # ", "# # ", "# #"],
+ "L": ["# ", "# ", "# ", "# ", "# ", "# ", "#####"],
+ "M": ["# #", "## ##", "# # #", "# #", "# #", "# #", "# #"],
+ "N": ["# #", "## #", "# # #", "# ##", "# #", "# #", "# #"],
+ "O": [" ### ", "# #", "# #", "# #", "# #", "# #", " ### "],
+ "R": ["#### ", "# #", "# #", "#### ", "# # ", "# # ", "# #"],
+ "S": [" ####", "# ", "# ", " ### ", " #", " #", "#### "],
+ "T": ["#####", " # ", " # ", " # ", " # ", " # ", " # "],
+ "U": ["# #", "# #", "# #", "# #", "# #", "# #", " ### "],
+ "W": ["# #", "# #", "# #", "# # #", "# # #", "## ##", "# #"],
+ "Y": ["# #", "# #", " # # ", " # ", " # ", " # ", " # "],
+ " ": [" "] * 7,
+}
+
+
+class Canvas:
+ def __init__(self, size):
+ self.size = size
+ self.px = bytearray(size * size) # palette indices, top row first
+
+ def dot(self, x, y, c):
+ if 0 <= x < self.size and 0 <= y < self.size:
+ self.px[y * self.size + x] = c
+
+ def rect(self, x0, y0, w, h, c):
+ for y in range(y0, y0 + h):
+ for x in range(x0, x0 + w):
+ self.dot(x, y, c)
+
+ def disc(self, cx, cy, r, c):
+ for y in range(int(cy - r), int(cy + r) + 1):
+ for x in range(int(cx - r), int(cx + r) + 1):
+ if (x - cx) ** 2 + (y - cy) ** 2 <= r * r:
+ self.dot(x, y, c)
+
+ def pill(self, x0, y0, w, h, c):
+ """A rectangle with round ends (the emblem's eyes)."""
+ r = w / 2
+ self.rect(x0, int(y0 + r), w, int(h - 2 * r), c)
+ self.disc(x0 + r - 0.5, y0 + r, r, c)
+ self.disc(x0 + r - 0.5, y0 + h - r, r, c)
+
+ def line(self, x0, y0, x1, y1, width, c):
+ steps = int(max(abs(x1 - x0), abs(y1 - y0))) + 1
+ for i in range(steps + 1):
+ t = i / steps
+ self.disc(x0 + (x1 - x0) * t, y0 + (y1 - y0) * t, width / 2, c)
+
+ def text(self, s, y, scale, colours, spacing=1):
+ """S centred at row Y; COLOURS gives each character's colour (a list as long as S, or one for all)."""
+ width = len(s) * (5 + spacing) * scale - spacing * scale
+ x = (self.size - width) // 2
+ for i, ch in enumerate(s):
+ c = colours[i] if isinstance(colours, list) else colours
+ for row, bits in enumerate(FONT[ch]):
+ for col, bit in enumerate(bits):
+ if bit == "#":
+ self.rect(x + col * scale, y + row * scale, scale, scale, c)
+ x += (5 + spacing) * scale
+
+ def emblem(self, cx, top, unit):
+ """The HakiOS emblem (the website's logo): a red head with two dark eyes and two ears, UNIT pixels to the logo's one."""
+ red = 1
+ u = unit
+ self.line(cx - 9.5 * u, top + 9 * u, cx - 13 * u, top + 0 * u, 2.2 * u, red) # ears
+ self.line(cx + 9.5 * u, top + 9 * u, cx + 13 * u, top + 0 * u, 2.2 * u, red)
+ self.disc(cx - 13 * u, top + 0 * u, 2.4 * u, red)
+ self.disc(cx + 13 * u, top + 0 * u, 2.4 * u, red)
+ self.disc(cx, top + 18.5 * u, 13 * u, red) # head
+ self.pill(int(cx - 6.5 * u), int(top + 14.5 * u), int(5 * u), int(7 * u), 0) # eyes
+ self.pill(int(cx + 1.5 * u), int(top + 14.5 * u), int(5 * u), int(7 * u), 0)
+
+ def bmp(self, path):
+ """An 8-bit BMP (BITMAPINFOHEADER, 256-colour palette, rows bottom-up, each a multiple of 4 bytes)."""
+ stride = (self.size + 3) & ~3
+ palette = b"".join(struct.pack("<BBBB", b, g, r, 0) for r, g, b in PALETTE + [INK] * (256 - len(PALETTE)))
+ rows = b"".join(bytes(self.px[y * self.size:(y + 1) * self.size]) + b"\0" * (stride - self.size)
+ for y in reversed(range(self.size)))
+ offset = 14 + 40 + len(palette)
+ header = struct.pack("<2sIHHI", b"BM", offset + len(rows), 0, 0, offset)
+ info = struct.pack("<IiiHHIIiiII", 40, self.size, self.size, 1, 8, 0, len(rows), 3779, 3779, 256, 256)
+ with open(path, "wb") as f:
+ f.write(header + info + palette + rows)
+
+
+def wordmark(c, y, scale):
+ c.text("HAKIOS", y, scale, [2, 2, 2, 2, 1, 1]) # HAKI in paper, OS in red: the website's wordmark
+
+
+def main():
+ if len(sys.argv) != 2:
+ sys.exit(__doc__)
+ out = sys.argv[1]
+ os.makedirs(out, exist_ok=True)
+
+ logo = Canvas(300)
+ logo.emblem(150, 40, 4.4)
+ wordmark(logo, 196, 6)
+ logo.bmp(os.path.join(out, "BootLogo.bmp"))
+
+ none = Canvas(300)
+ none.emblem(150, 30, 3.2)
+ wordmark(none, 150, 5)
+ none.text("NO SYSTEM", 214, 3, 3)
+ none.text("TO BOOT", 244, 3, 3)
+ none.bmp(os.path.join(out, "NoBootOS.bmp"))
+
+ storage = Canvas(500)
+ storage.emblem(250, 60, 6)
+ wordmark(storage, 300, 8)
+ storage.text("USB MASS STORAGE", 400, 4, 3)
+ storage.bmp(os.path.join(out, "MassStorage.bmp"))
+ print("banner: BootLogo.bmp, NoBootOS.bmp, MassStorage.bmp written to %s" % out)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/uefi/export.sh b/uefi/export.sh
new file mode 100755
index 0000000..213940e
--- /dev/null
+++ b/uefi/export.sh
@@ -0,0 +1,15 @@
+#!/bin/bash
+# The reverse of uefi/apply.sh: what was changed in Mu-Silicium/ goes back here. The changes to Silicium's own files go to
+# hakios.patch, HakiOS's new files under Silicon/ to files/, and each device's platform to devices/<name>/uefi/files/
+# (devices/<name>/uefi/export.sh). The banner pictures are made by branding/banner.py and are not saved: change that instead.
+set -e
+HERE=$(cd "$(dirname "$(readlink -f "$0")")" && pwd)
+ROOT=$(dirname "$HERE")
+MU=${MU:-$ROOT/Mu-Silicium}
+[ "$(git -C "$MU" rev-parse HEAD)" = "$(cat "$HERE/BASE")" ] || { echo "uefi/export.sh: $MU is not at BASE"; exit 1; }
+git -C "$MU" diff -- BootShim Silicon ':!Silicon/Silicium/SiliciumPkg/Include/Resources' > "$HERE/hakios.patch"
+rm -rf "$HERE/files"
+mkdir -p "$HERE/files/Silicon/Silicium/SiliciumPkg/Library/BootManagerLib"
+cp "$MU"/Silicon/Silicium/SiliciumPkg/Library/BootManagerLib/XnuLoader.[ch] "$HERE/files/Silicon/Silicium/SiliciumPkg/Library/BootManagerLib/"
+for d in "$ROOT"/devices/*/uefi/export.sh; do [ -x "$d" ] && "$d"; done
+echo "uefi/export.sh: patch $(wc -l < "$HERE/hakios.patch") lines, $(find "$HERE/files" -type f | wc -l) files"
diff --git a/uefi/hakios.patch b/uefi/hakios.patch
new file mode 100644
index 0000000..650a2bd
--- /dev/null
+++ b/uefi/hakios.patch
@@ -0,0 +1,659 @@
+diff --git a/BootShim/BootShim.S b/BootShim/BootShim.S
+index 4d20855..3c3b17b 100644
+--- a/BootShim/BootShim.S
++++ b/BootShim/BootShim.S
+@@ -28,6 +28,27 @@ _CopyLoop:
+ stp x2, x3, [x5], #16
+ subs x6, x6, #16
+ b.ne _CopyLoop
++
++#ifdef PAYLOAD_BASE
++ /* x4 now points just past the FD: an optional "XNUP" payload may follow */
++ ldr w2, [x4]
++ movz w3, #0x4E58
++ movk w3, #0x5055, lsl #16
++ cmp w2, w3
++ b.ne _NoPayload
++ ldr w6, [x4, #4] /* Payload Size */
++ add x6, x6, #23 /* Header + Round Up to 16 */
++ and x6, x6, #~15
++ movz x5, #(PAYLOAD_BASE >> 16), lsl #16
++
++_PayloadLoop:
++ ldp x2, x3, [x4], #16
++ stp x2, x3, [x5], #16
++ subs x6, x6, #16
++ b.ne _PayloadLoop
++
++_NoPayload:
++#endif
+ ldr x5, =FD_BASE
+
+ _Entry:
+diff --git a/Silicon/Silicium/SiliciumPkg/Library/BootManagerLib/BootManager.c b/Silicon/Silicium/SiliciumPkg/Library/BootManagerLib/BootManager.c
+index 9b18ddb..f5bff32 100644
+--- a/Silicon/Silicium/SiliciumPkg/Library/BootManagerLib/BootManager.c
++++ b/Silicon/Silicium/SiliciumPkg/Library/BootManagerLib/BootManager.c
+@@ -1,241 +1,245 @@
+-/**
+- Copyright (C) DuoWoA authors. All rights reserved.
+- Copyright (C) Microsoft Corporation. All rights reserved.
+-
+- SPDX-License-Identifier: BSD-2-Clause-Patent
+-**/
+-
+-#include <Library/PcdLib.h>
+-#include <Library/DebugLib.h>
+-#include <Library/AcpiTableUpdateLib.h>
+-#include <Library/DeviceBootManagerLib.h>
+-#include <Library/PlatformBootManagerLib.h>
+-#include <Library/UefiRuntimeServicesTableLib.h>
+-#include <Library/UefiBootServicesTableLib.h>
+-#include <Library/SecureBootHandlerLib.h>
+-#include <Library/MemoryAllocationLib.h>
+-#include <Library/MsBootOptionsLib.h>
+-#include <Library/BootGraphicsLib.h>
+-#include <Library/BootGraphics.h>
+-#include <Library/PrintLib.h>
+-
+-#include <Configuration/BootDevices.h>
+-
+-#include "BootManager.h"
+-
+-//
+-// Global Variables
+-//
+-STATIC UINTN XPos = 0;
+-STATIC UINTN YPos = 0;
+-
+-//
+-// BDS Combo Message
+-//
+-STATIC CONST CHAR8 *ComboMessage = "[Volume Up] Boot Manager";
+-
+-VOID
+-EFIAPI
+-PlatformBootManagerBeforeConsole ()
+-{
+- // Signal End Of DXE
+- EfiEventGroupSignal (&gEfiEndOfDxeEventGroupGuid);
+-
+- // Dispatch Deferred Images
+- EfiBootManagerDispatchDeferredImages ();
+-
+- // Register Boot Options
+- MsBootOptionsLibRegisterDefaultBootOptions ();
+-
+- // Register Console Variables
+- EfiBootManagerUpdateConsoleVariable (ConIn, (EFI_DEVICE_PATH_PROTOCOL *)&KeypadDevicePath, NULL);
+- EfiBootManagerUpdateConsoleVariable (ConOut, (EFI_DEVICE_PATH_PROTOCOL *)&DisplayDevicePath, NULL);
+- EfiBootManagerUpdateConsoleVariable (ErrOut, (EFI_DEVICE_PATH_PROTOCOL *)&DisplayDevicePath, NULL);
+-
+- // Execute Secondary Before Console
+- DeviceBootManagerBeforeConsole (NULL, NULL);
+-}
+-
+-VOID
+-PostGopSetup (OUT EFI_GRAPHICS_OUTPUT_PROTOCOL **GopProtocol)
+-{
+- EFI_STATUS Status;
+- EFI_GRAPHICS_OUTPUT_PROTOCOL *LocalGopProtocol;
+-
+- // Verify Parameters
+- if (GopProtocol == NULL) {
+- return;
+- }
+-
+- // Locate GOP Protocol
+- Status = gBS->HandleProtocol (gST->ConsoleOutHandle, &gEfiGraphicsOutputProtocolGuid, (VOID *)&LocalGopProtocol);
+- if (EFI_ERROR (Status) && Status != EFI_UNSUPPORTED) {
+- DEBUG ((EFI_D_ERROR, "%a: Failed to Locate GOP Protocol from Handle! Status = %r\n", __FUNCTION__, Status));
+- return;
+- }
+-
+- // Check Status
+- if (Status == EFI_UNSUPPORTED) {
+- // Locate GOP Protocol
+- Status = gBS->LocateProtocol (&gEfiGraphicsOutputProtocolGuid, NULL, (VOID *)&LocalGopProtocol);
+- if (EFI_ERROR (Status)) {
+- DEBUG ((EFI_D_ERROR, "%a: Failed to Locate GOP Protocol! Status = %r\n", __FUNCTION__, Status));
+- return;
+- }
+-
+- // Install GOP Protocol
+- Status = gBS->InstallProtocolInterface (&gST->ConsoleOutHandle, &gEfiGraphicsOutputProtocolGuid, EFI_NATIVE_INTERFACE, LocalGopProtocol);
+- if (EFI_ERROR (Status)) {
+- DEBUG ((EFI_D_ERROR, "%a: Failed to Install GOP Protocol onto \"ConsoleOutHandle\"! Status = %r\n", __FUNCTION__, Status));
+- }
+- }
+-
+- // Pass GOP Protocol
+- *GopProtocol = LocalGopProtocol;
+-}
+-
+-VOID
+-EFIAPI
+-PlatformBootManagerAfterConsole ()
+-{
+- EFI_STATUS Status = EFI_SUCCESS;
+- EFI_GRAPHICS_OUTPUT_PROTOCOL *GopProtocol = NULL;
+-
+- // Post Setup GOP
+- PostGopSetup (&GopProtocol);
+-
+- // Display Boot Logo
+- Status = DisplayBootGraphic (BG_SYSTEM_LOGO);
+- if (EFI_ERROR (Status)) {
+- DEBUG ((EFI_D_ERROR, "%a: Failed to Display Boot Logo! Status = %r\n", __FUNCTION__, Status));
+- }
+-
+- // Register Key Callback
+- Status = RegisterKeyCallback ((EFI_DEVICE_PATH_PROTOCOL *)&KeypadDevicePath);
+- if (!EFI_ERROR (Status) && GopProtocol != NULL) {
+- // Set Screen Resolution
+- UINT32 ScreenWidth = GopProtocol->Mode->Info->HorizontalResolution;
+- UINT32 ScreenHeight = GopProtocol->Mode->Info->VerticalResolution;
+-
+- // Set Combo Message Position
+- XPos = (ScreenWidth - AsciiStrLen (ComboMessage) * EFI_GLYPH_WIDTH) / 2;
+- YPos = ScreenHeight * 48 / 50;
+- }
+-
+- // Execute Secondary After Console
+- DeviceBootManagerAfterConsole ();
+-}
+-
+-VOID
+-EFIAPI
+-PlatformBootManagerOnDemandConInConnect ()
+-{
+- // Execute Secondary On Demand
+- DeviceBootManagerOnDemandConInConnect ();
+-}
+-
+-VOID
+-EFIAPI
+-PlatformBootManagerProcessBootCompletion (OUT EFI_BOOT_MANAGER_LOAD_OPTION *BootOption)
+-{
+- return;
+-}
+-
+-VOID
+-EFIAPI
+-PlatformBootManagerPriorityBoot (IN OUT UINT16 **BootNext)
+-{
+- EFI_STATUS Status;
+- EFI_BOOT_MANAGER_LOAD_OPTION LoadOption;
+- BOOLEAN BootManagerFlag;
+-
+- // Unregister Key Callback
+- UnregisterKeyCallback ();
+-
+- // Get Boot Manager Flag
+- BootManagerFlag = EnterBootManager ();
+- if (BootManagerFlag == FALSE) {
+- return;
+- }
+-
+- // Get Boot Manager Load Option
+- Status = MsBootOptionsLibGetBootManagerMenu (&LoadOption, NULL);
+- if (EFI_ERROR (Status)) {
+- DEBUG ((EFI_D_ERROR, "%a: Failed to get Boot Manager Load Option! Status = %r", __FUNCTION__, Status));
+- return;
+- }
+-
+- // Execute Boot Manager Load Option
+- EfiBootManagerBoot (&LoadOption);
+- EfiBootManagerFreeLoadOption (&LoadOption);
+-}
+-
+-VOID
+-EFIAPI
+-PlatformBootManagerWaitCallback (IN UINT16 TimeoutRemain)
+-{
+- EFI_GRAPHICS_OUTPUT_BLT_PIXEL Color;
+-
+- // Verify Combo Message Position
+- if (XPos == 0 && YPos == 0) {
+- return;
+- }
+-
+- // Get Timeout Time
+- UINT16 Timeout = PcdGet16 (PcdPlatformBootTimeOut);
+-
+- // Check Remaining Timeout
+- if (TimeoutRemain == Timeout || TimeoutRemain == 0) {
+- // Set Draw Color
+- UINT8 DrawColor = (TimeoutRemain == Timeout) ? 0xFF : 0x00;
+-
+- // Set GOP Draw Color
+- Color.Red = Color.Green = Color.Blue = DrawColor;
+-
+- // Print Combo Message
+- AsciiPrintXY (XPos, YPos, &Color, NULL, ComboMessage);
+- }
+-}
+-
+-VOID
+-EFIAPI
+-PlatformBootManagerUnableToBoot ()
+-{
+- EFI_STATUS Status;
+-
+- // Execute Secondary Unable To Boot
+- DeviceBootManagerUnableToBoot ();
+-
+- // Display No Boot OS Logo
+- Status = DisplayBootGraphic (BG_NO_BOOT_OS);
+- if (EFI_ERROR (Status)) {
+- DEBUG ((EFI_D_ERROR, "%a: Failed to Display No Boot OS Logo! Status = %r\n", __FUNCTION__, Status));
+- Print (L"No Operating System Found! Please make sure that an OS is Installed.\n");
+- }
+-
+- // Wait 10s
+- gBS->Stall (10000000);
+-
+- // Shutdown
+- gRT->ResetSystem (EfiResetShutdown, EFI_SUCCESS, 0, NULL);
+-
+- // Do Cpu Dead Loop
+- CpuDeadLoop ();
+-}
+-
+-VOID
+-EFIAPI
+-PlatformBootManagerBdsEntry ()
+-{
+- EFI_STATUS Status;
+-
+- // Setup Secure Boot
+- Status = SetupSecureBoot ();
+- ASSERT_EFI_ERROR (Status);
+-
+- // Update ACPI Tables
+- UpdateAcpiTables ();
+-
+- // Execute Secondary BDS Entry
+- DeviceBootManagerBdsEntry ();
+-}
++/**
++ Copyright (C) DuoWoA authors. All rights reserved.
++ Copyright (C) Microsoft Corporation. All rights reserved.
++
++ SPDX-License-Identifier: BSD-2-Clause-Patent
++**/
++
++#include <Library/PcdLib.h>
++#include <Library/DebugLib.h>
++#include <Library/AcpiTableUpdateLib.h>
++#include <Library/DeviceBootManagerLib.h>
++#include <Library/PlatformBootManagerLib.h>
++#include <Library/UefiRuntimeServicesTableLib.h>
++#include <Library/UefiBootServicesTableLib.h>
++#include <Library/SecureBootHandlerLib.h>
++#include <Library/MemoryAllocationLib.h>
++#include <Library/MsBootOptionsLib.h>
++#include <Library/BootGraphicsLib.h>
++#include <Library/BootGraphics.h>
++#include <Library/PrintLib.h>
++
++#include <Configuration/BootDevices.h>
++
++#include "BootManager.h"
++#include "XnuLoader.h"
++
++//
++// Global Variables
++//
++STATIC UINTN XPos = 0;
++STATIC UINTN YPos = 0;
++
++//
++// BDS Combo Message
++//
++STATIC CONST CHAR8 *ComboMessage = "[Volume Up] Boot Manager";
++
++VOID
++EFIAPI
++PlatformBootManagerBeforeConsole ()
++{
++ // Signal End Of DXE
++ EfiEventGroupSignal (&gEfiEndOfDxeEventGroupGuid);
++
++ // Dispatch Deferred Images
++ EfiBootManagerDispatchDeferredImages ();
++
++ // Register Boot Options
++ MsBootOptionsLibRegisterDefaultBootOptions ();
++
++ // Register Console Variables
++ EfiBootManagerUpdateConsoleVariable (ConIn, (EFI_DEVICE_PATH_PROTOCOL *)&KeypadDevicePath, NULL);
++ EfiBootManagerUpdateConsoleVariable (ConOut, (EFI_DEVICE_PATH_PROTOCOL *)&DisplayDevicePath, NULL);
++ EfiBootManagerUpdateConsoleVariable (ErrOut, (EFI_DEVICE_PATH_PROTOCOL *)&DisplayDevicePath, NULL);
++
++ // Execute Secondary Before Console
++ DeviceBootManagerBeforeConsole (NULL, NULL);
++}
++
++VOID
++PostGopSetup (OUT EFI_GRAPHICS_OUTPUT_PROTOCOL **GopProtocol)
++{
++ EFI_STATUS Status;
++ EFI_GRAPHICS_OUTPUT_PROTOCOL *LocalGopProtocol;
++
++ // Verify Parameters
++ if (GopProtocol == NULL) {
++ return;
++ }
++
++ // Locate GOP Protocol
++ Status = gBS->HandleProtocol (gST->ConsoleOutHandle, &gEfiGraphicsOutputProtocolGuid, (VOID *)&LocalGopProtocol);
++ if (EFI_ERROR (Status) && Status != EFI_UNSUPPORTED) {
++ DEBUG ((EFI_D_ERROR, "%a: Failed to Locate GOP Protocol from Handle! Status = %r\n", __FUNCTION__, Status));
++ return;
++ }
++
++ // Check Status
++ if (Status == EFI_UNSUPPORTED) {
++ // Locate GOP Protocol
++ Status = gBS->LocateProtocol (&gEfiGraphicsOutputProtocolGuid, NULL, (VOID *)&LocalGopProtocol);
++ if (EFI_ERROR (Status)) {
++ DEBUG ((EFI_D_ERROR, "%a: Failed to Locate GOP Protocol! Status = %r\n", __FUNCTION__, Status));
++ return;
++ }
++
++ // Install GOP Protocol
++ Status = gBS->InstallProtocolInterface (&gST->ConsoleOutHandle, &gEfiGraphicsOutputProtocolGuid, EFI_NATIVE_INTERFACE, LocalGopProtocol);
++ if (EFI_ERROR (Status)) {
++ DEBUG ((EFI_D_ERROR, "%a: Failed to Install GOP Protocol onto \"ConsoleOutHandle\"! Status = %r\n", __FUNCTION__, Status));
++ }
++ }
++
++ // Pass GOP Protocol
++ *GopProtocol = LocalGopProtocol;
++}
++
++VOID
++EFIAPI
++PlatformBootManagerAfterConsole ()
++{
++ EFI_STATUS Status = EFI_SUCCESS;
++ EFI_GRAPHICS_OUTPUT_PROTOCOL *GopProtocol = NULL;
++
++ // Post Setup GOP
++ PostGopSetup (&GopProtocol);
++
++ // Display Boot Logo
++ Status = DisplayBootGraphic (BG_SYSTEM_LOGO);
++ if (EFI_ERROR (Status)) {
++ DEBUG ((EFI_D_ERROR, "%a: Failed to Display Boot Logo! Status = %r\n", __FUNCTION__, Status));
++ }
++
++ // Register Key Callback
++ Status = RegisterKeyCallback ((EFI_DEVICE_PATH_PROTOCOL *)&KeypadDevicePath);
++ if (!EFI_ERROR (Status) && GopProtocol != NULL) {
++ // Set Screen Resolution
++ UINT32 ScreenWidth = GopProtocol->Mode->Info->HorizontalResolution;
++ UINT32 ScreenHeight = GopProtocol->Mode->Info->VerticalResolution;
++
++ // Set Combo Message Position
++ XPos = (ScreenWidth - AsciiStrLen (ComboMessage) * EFI_GLYPH_WIDTH) / 2;
++ YPos = ScreenHeight * 48 / 50;
++ }
++
++ // Execute Secondary After Console
++ DeviceBootManagerAfterConsole ();
++}
++
++VOID
++EFIAPI
++PlatformBootManagerOnDemandConInConnect ()
++{
++ // Execute Secondary On Demand
++ DeviceBootManagerOnDemandConInConnect ();
++}
++
++VOID
++EFIAPI
++PlatformBootManagerProcessBootCompletion (OUT EFI_BOOT_MANAGER_LOAD_OPTION *BootOption)
++{
++ return;
++}
++
++VOID
++EFIAPI
++PlatformBootManagerPriorityBoot (IN OUT UINT16 **BootNext)
++{
++ EFI_STATUS Status;
++ EFI_BOOT_MANAGER_LOAD_OPTION LoadOption;
++ BOOLEAN BootManagerFlag;
++
++ // Unregister Key Callback
++ UnregisterKeyCallback ();
++
++ // Get Boot Manager Flag
++ BootManagerFlag = EnterBootManager ();
++ if (BootManagerFlag == FALSE) {
++ return;
++ }
++
++ // Get Boot Manager Load Option
++ Status = MsBootOptionsLibGetBootManagerMenu (&LoadOption, NULL);
++ if (EFI_ERROR (Status)) {
++ DEBUG ((EFI_D_ERROR, "%a: Failed to get Boot Manager Load Option! Status = %r", __FUNCTION__, Status));
++ return;
++ }
++
++ // Execute Boot Manager Load Option
++ EfiBootManagerBoot (&LoadOption);
++ EfiBootManagerFreeLoadOption (&LoadOption);
++}
++
++VOID
++EFIAPI
++PlatformBootManagerWaitCallback (IN UINT16 TimeoutRemain)
++{
++ EFI_GRAPHICS_OUTPUT_BLT_PIXEL Color;
++
++ // Verify Combo Message Position
++ if (XPos == 0 && YPos == 0) {
++ return;
++ }
++
++ // Get Timeout Time
++ UINT16 Timeout = PcdGet16 (PcdPlatformBootTimeOut);
++
++ // Check Remaining Timeout
++ if (TimeoutRemain == Timeout || TimeoutRemain == 0) {
++ // Set Draw Color
++ UINT8 DrawColor = (TimeoutRemain == Timeout) ? 0xFF : 0x00;
++
++ // Set GOP Draw Color
++ Color.Red = Color.Green = Color.Blue = DrawColor;
++
++ // Print Combo Message
++ AsciiPrintXY (XPos, YPos, &Color, NULL, ComboMessage);
++ }
++}
++
++VOID
++EFIAPI
++PlatformBootManagerUnableToBoot ()
++{
++ EFI_STATUS Status;
++
++ // Nothing else to boot: hand over to the XNU loader (does not return)
++ XnuLoaderMain ();
++
++ // Execute Secondary Unable To Boot
++ DeviceBootManagerUnableToBoot ();
++
++ // Display No Boot OS Logo
++ Status = DisplayBootGraphic (BG_NO_BOOT_OS);
++ if (EFI_ERROR (Status)) {
++ DEBUG ((EFI_D_ERROR, "%a: Failed to Display No Boot OS Logo! Status = %r\n", __FUNCTION__, Status));
++ Print (L"No Operating System Found! Please make sure that an OS is Installed.\n");
++ }
++
++ // Wait 10s
++ gBS->Stall (10000000);
++
++ // Shutdown
++ gRT->ResetSystem (EfiResetShutdown, EFI_SUCCESS, 0, NULL);
++
++ // Do Cpu Dead Loop
++ CpuDeadLoop ();
++}
++
++VOID
++EFIAPI
++PlatformBootManagerBdsEntry ()
++{
++ EFI_STATUS Status;
++
++ // Setup Secure Boot
++ Status = SetupSecureBoot ();
++ ASSERT_EFI_ERROR (Status);
++
++ // Update ACPI Tables
++ UpdateAcpiTables ();
++
++ // Execute Secondary BDS Entry
++ DeviceBootManagerBdsEntry ();
++}
+diff --git a/Silicon/Silicium/SiliciumPkg/Library/BootManagerLib/BootManagerLib.inf b/Silicon/Silicium/SiliciumPkg/Library/BootManagerLib/BootManagerLib.inf
+index 2310dc6..12a5a5d 100644
+--- a/Silicon/Silicium/SiliciumPkg/Library/BootManagerLib/BootManagerLib.inf
++++ b/Silicon/Silicium/SiliciumPkg/Library/BootManagerLib/BootManagerLib.inf
+@@ -1,50 +1,55 @@
+-##
+-# Copyright (C) Microsoft Corporation. All rights reserved.
+-# SPDX-License-Identifier: BSD-2-Clause-Patent
+-##
+-
+-[Defines]
+- INF_VERSION = 0x00010018
+- BASE_NAME = BootManagerLib
+- FILE_GUID = DF8F3324-5448-46BC-872C-BE198ECF2F76
+- VERSION_STRING = 1.0
+- MODULE_TYPE = DXE_DRIVER
+- UEFI_SPECIFICATION_VERSION = 2.7
+- LIBRARY_CLASS = PlatformBootManagerLib|DXE_DRIVER
+-
+-[Sources]
+- BootManager.c
+- KeyCallback.c
+-
+-[Packages]
+- MdePkg/MdePkg.dec
+- PcBdsPkg/PcBdsPkg.dec
+- MsCorePkg/MsCorePkg.dec
+- MsGraphicsPkg/MsGraphicsPkg.dec
+- MdeModulePkg/MdeModulePkg.dec
+- SiliciumPkg/SiliciumPkg.dec
+-
+-[LibraryClasses]
+- PcdLib
+- DebugLib
+- AcpiTableUpdateLib
+- DeviceBootManagerLib
+- UefiRuntimeServicesTableLib
+- UefiBootServicesTableLib
+- SecureBootHandlerLib
+- MemoryAllocationLib
+- MsBootOptionsLib
+- BootGraphicsLib
+- DevicePathLib
+- PrintLib
+-
+-[Pcd]
+- gEfiMdePkgTokenSpaceGuid.PcdPlatformBootTimeOut
+-
+-[Guids]
+- gEfiEndOfDxeEventGroupGuid
+-
+-[Protocols]
+- gKeypadDeviceProtocolGuid
+- gEfiGraphicsOutputProtocolGuid
+- gEfiSimpleTextInputExProtocolGuid
++##
++# Copyright (C) Microsoft Corporation. All rights reserved.
++# SPDX-License-Identifier: BSD-2-Clause-Patent
++##
++
++[Defines]
++ INF_VERSION = 0x00010018
++ BASE_NAME = BootManagerLib
++ FILE_GUID = DF8F3324-5448-46BC-872C-BE198ECF2F76
++ VERSION_STRING = 1.0
++ MODULE_TYPE = DXE_DRIVER
++ UEFI_SPECIFICATION_VERSION = 2.7
++ LIBRARY_CLASS = PlatformBootManagerLib|DXE_DRIVER
++
++[Sources]
++ BootManager.c
++ XnuLoader.c
++ KeyCallback.c
++
++[Packages]
++ MdePkg/MdePkg.dec
++ PcBdsPkg/PcBdsPkg.dec
++ MsCorePkg/MsCorePkg.dec
++ MsGraphicsPkg/MsGraphicsPkg.dec
++ MdeModulePkg/MdeModulePkg.dec
++ SiliciumPkg/SiliciumPkg.dec
++
++[LibraryClasses]
++ PcdLib
++ DebugLib
++ AcpiTableUpdateLib
++ DeviceBootManagerLib
++ UefiRuntimeServicesTableLib
++ UefiBootServicesTableLib
++ SecureBootHandlerLib
++ MemoryAllocationLib
++ MsBootOptionsLib
++ BootGraphicsLib
++ DevicePathLib
++ PrintLib
++ BaseLib
++ BaseMemoryLib
++
++[Pcd]
++ gEfiMdePkgTokenSpaceGuid.PcdPlatformBootTimeOut
++
++[Guids]
++ gEfiEndOfDxeEventGroupGuid
++
++[Protocols]
++ gKeypadDeviceProtocolGuid
++ gEfiGraphicsOutputProtocolGuid
++ gEfiSimpleTextInputExProtocolGuid
++ gEfiBlockIoProtocolGuid
++ gEfiPartitionInfoProtocolGuid
+diff --git a/Silicon/Silicium/SiliciumPkg/Sec/Sec.c b/Silicon/Silicium/SiliciumPkg/Sec/Sec.c
+index 8d586b3..511fc76 100644
+--- a/Silicon/Silicium/SiliciumPkg/Sec/Sec.c
++++ b/Silicon/Silicium/SiliciumPkg/Sec/Sec.c
+@@ -44,7 +44,7 @@ PrintFirmwareVersion (VOID)
+
+ // Print UEFI Version Message
+ DEBUG ((EFI_D_WARN, "\n"));
+- DEBUG ((EFI_D_WARN, "Project Silicium for %a %a\n", FixedPcdGetPtr (PcdSmbiosSystemManufacturer), FixedPcdGetPtr (PcdSmbiosSystemModel)));
++ DEBUG ((EFI_D_WARN, "HakiOS UEFI (Mu-Silicium) for %a %a\n", FixedPcdGetPtr (PcdSmbiosSystemManufacturer), FixedPcdGetPtr (PcdSmbiosSystemModel)));
+ DEBUG ((EFI_D_WARN, "Firmware Version %s Build at %a on %a\n", PcdGetPtr (PcdFirmwareVersionString), __TIME__, __DATE__));
+ DEBUG ((EFI_D_WARN, "\n"));
+ }
+diff --git a/Silicon/Silicium/SiliciumPkg/SiliciumPkg.dsc.inc b/Silicon/Silicium/SiliciumPkg/SiliciumPkg.dsc.inc
+index 00ec09e..a936a7b 100644
+--- a/Silicon/Silicium/SiliciumPkg/SiliciumPkg.dsc.inc
++++ b/Silicon/Silicium/SiliciumPkg/SiliciumPkg.dsc.inc
+@@ -36,7 +36,7 @@
+ # Firmware Details
+ #
+ gEfiMdeModulePkgTokenSpaceGuid.PcdFirmwareVersionString|L"4.0"
+- gEfiMdeModulePkgTokenSpaceGuid.PcdFirmwareVendor|L"Project Silicium"
++ gEfiMdeModulePkgTokenSpaceGuid.PcdFirmwareVendor|L"HakiOS"
+
+ #
+ # Memory
diff --git a/xnu-build.sh b/xnu-build.sh
index 7af6e62..673a45f 100755
--- a/xnu-build.sh
+++ b/xnu-build.sh
@@ -5,6 +5,8 @@ cd "$XNU_SRC" || exit 1
# The Wi-Fi driver's object (tools/mk-ath11k.sh) is linked into the kernel when it is there; make
# does not see it change, so the linked kernel is thrown away when it has.
LX=$XNUDEPS/build/ath11k/out/ath11k.o
+# ... only into a kernel that has the Wi-Fi driver (CONFIG_HAKIOS_WIFI): the object's calls are answered by hakios.lx.c
+if [ -f config/MASTER.hakios ] && ! grep -q '^# HAKIOS_DRIVERS = \[.* hakios_wifi ' config/MASTER.hakios; then LX=/nonexistent; fi
STAMP=BUILD/obj/hakios-objects
mtime() { if [ "$XNU_HOST_OS" = Darwin ]; then stat -f %m "$1"; else stat -c %Y "$1"; fi; }
if [ -f "$LX" ]; then now="$LX $(mtime "$LX")"; else LX= now=; fi
diff --git a/xnu/apply.sh b/xnu/apply.sh
index 50cad91..c932c0e 100755
--- a/xnu/apply.sh
+++ b/xnu/apply.sh
@@ -38,4 +38,13 @@ while read -r sub tree _; do
cp -p "$HERE/../drivers/$sub/$(basename "$tree")" "$tree"
NDRIVERS=$((NDRIVERS + 1))
done < "$HERE/../drivers/map"
+# the drivers of the SoC and device repositories checked out (socs/*/drivers/, devices/*/drivers/)
+python3 "$HERE/../tools/hakios-config.py" external-files | while IFS="$(printf '\t')" read -r src tree; do
+ mkdir -p "$(dirname "$tree")"
+ cp -p "$src" "$tree"
+done
+# which of them are built is the configuration's (drivers/*/conf, CONFIG_HAKIOS_*): put into the tree as XNU reads it.
+# What that writes is made again for every build, so it is kept out of the work that xnu/export.sh saves.
+printf '%s\n' config/MASTER.hakios bsd/dev/hakios.drivers.h >> .git/info/exclude
+python3 "$HERE/../tools/hakios-config.py" kernel --tree "$DIR"
echo "apply.sh: $DIR: $TAG + $(grep -c '^diff --git' "$HERE/hakios.patch") changed and $(find "$HERE/files" -type f | wc -l) new files + $NDRIVERS drivers"
diff --git a/xnu/export.sh b/xnu/export.sh
index f7f5005..305844b 100755
--- a/xnu/export.sh
+++ b/xnu/export.sh
@@ -10,7 +10,8 @@ HERE=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
SRC=${1:-${XNU_SRC:-$HERE/../xnu-src/xnu-8796.121.2}}
BASE=c54f35ca767986246321eb901baf8f5ff7923f6a # tag xnu-8796.121.2
# never part of the work: build output and what editors, patch and python leave behind
-JUNK='^BUILD/|(^|/)__pycache__/|\.(orig|rej|pyc|o|swp)$|\.bak[0-9]*$|~$|(^|/)\.DS_Store$'
+# nor what tools/hakios-config.py kernel writes for one configuration (the drivers' choice)
+JUNK='^BUILD/|^config/MASTER\.hakios$|^bsd/dev/hakios\.drivers\.h$|(^|/)__pycache__/|\.(orig|rej|pyc|o|swp)$|\.bak[0-9]*$|~$|(^|/)\.DS_Store$'
cd "$SRC"
git cat-file -e "$BASE^{commit}" 2>/dev/null || { echo "export.sh: $SRC is not a clone of xnu at $BASE" >&2; exit 1; }
@@ -29,6 +30,13 @@ while IFS= read -r f; do
if [ "$(uname)" = Darwin ]; then cp -pP "$f" "$HERE/files.new/$f"; else cp -P --preserve=mode "$f" "$HERE/files.new/$f"; fi
done < "$HERE/files.list"
+# The drivers of SoC and device repositories (tools/hakios-config.py external-files) are theirs, not this repository's: they are
+# left out of files/ and are not refused as unlisted. Edit them in their repository; xnu/sync-drivers.sh copies them in.
+EXTERNAL=$(python3 "$HERE/../tools/hakios-config.py" external-files | cut -f2)
+if [ -n "$EXTERNAL" ]; then
+ printf '%s\n' "$EXTERNAL" | while IFS= read -r tree; do rm -f "$HERE/files.new/$tree"; done
+fi
+
# The drivers (drivers/map) are kept by subsystem in drivers/<subsystem>/, not under files/: take them out of
# files.new and put each one where the map says. A hakios.* file the map does not list is refused, not guessed at.
MAP="$HERE/../drivers/map"
diff --git a/xnu/files/bsd/sys/hakios.audio.h b/xnu/files/bsd/sys/hakios.audio.h
index 20364cd..59ad01d 100644
--- a/xnu/files/bsd/sys/hakios.audio.h
+++ b/xnu/files/bsd/sys/hakios.audio.h
@@ -74,7 +74,7 @@ void hakios_speaker_quiesce(void); /* powered down at once, without sleeping
uint32_t hakios_speaker_monitor(bool tell);
/*
- * The speakers' guard (drivers/storage/hakios.guard.c): what the samples go through in the feeder on their
+ * The speakers' guard (drivers/audio/hakios.guard.c): what the samples go through in the feeder on their
* way to the amplifiers, for want of the DSP's speaker protection. Levels in eighths of a dB.
*/
#define HAKIOS_GUARD_SILENT 0xffffffffu /* the amplifiers are off: nothing reaches the speakers */
diff --git a/xnu/files/bsd/sys/hakios.input.h b/xnu/files/bsd/sys/hakios.input.h
index d295c19..07125e1 100644
--- a/xnu/files/bsd/sys/hakios.input.h
+++ b/xnu/files/bsd/sys/hakios.input.h
@@ -46,6 +46,8 @@ void hakios_ufs_init(void); /* ufs=2 to xnuloader: the phone's storage
void hakios_ufs_report(const char *when); /* where reading the storage has spent its time so far */
bool hakios_ufs_dev(dev_t dev); /* one of the storage's devices */
int hakios_ufs_read_partition(const char *name, uint64_t offset, uint8_t *dst, uint64_t len, uint64_t *bytes); /* for drivers */
+/* a file of one of the RAM disks (drivers/storage/hakios.image.c): fw/<name> is the firmware userland/build.sh put there */
+const uint8_t *hakios_image_file(const char *dir, const char *name, uint64_t *size, int *disk_out);
void hakios_battery_init(void); /* boot-arg battery=1: Qualcomm UEFI charger state shared by xnuloader */
int hakios_battery_temperature(void); /* the battery's temperature in C, -273 while it is not known */
/* one transfer at a time through the PMIC arbiter for this system (drivers/input/hakios.buttons.c) */
diff --git a/xnu/hakios.patch b/xnu/hakios.patch
index 8261520..0386087 100644
--- a/xnu/hakios.patch
+++ b/xnu/hakios.patch
@@ -36,7 +36,7 @@ index e78d8476c346..03fc3ff646b8 100644
TOP_TARGETS = \
diff --git a/SETUP/config/doconf b/SETUP/config/doconf
-index 222158a93918..68bb0f3e56bf 100755
+index 222158a93918..030e55b82ac1 100755
--- a/SETUP/config/doconf
+++ b/SETUP/config/doconf
@@ -1,4 +1,4 @@
@@ -45,6 +45,45 @@ index 222158a93918..68bb0f3e56bf 100755
set path = ($path .)
######################################################################
# HISTORY
+@@ -184,6 +184,13 @@ if ($?beverbose) then
+ echo MASTER_CPU=$MASTER_CPU
+ endif
+
++# HakiOS: the drivers a configuration builds (CONFIG_HAKIOS_*), as tools/hakios-config.py kernel writes them: a list
++# HAKIOS_DRIVERS of attributes, which the configurations of MASTER.arm64.bcm2837 include, and an `options` line for each
++set MASTER_HAKIOS = /dev/null
++if (-f ${MASTER_DIR}/MASTER.hakios) then
++ set MASTER_HAKIOS = ${MASTER_DIR}/MASTER.hakios
++endif
++
+ foreach SYS ($argv)
+ set SYSID=${SYS}_${ID}
+ set SYSCONF=$OBJDIR/config.$SYSID
+@@ -193,8 +200,8 @@ foreach SYS ($argv)
+ endif
+ echo +$SYS \
+ | \
+- cat $MASTER $MASTER_CPU - \
+- $MASTER $MASTER_CPU \
++ cat $MASTER $MASTER_CPU $MASTER_HAKIOS - \
++ $MASTER $MASTER_CPU $MASTER_HAKIOS \
+ | \
+ unifdef -t -DPLATFORM_${PLATFORM} -DCPU_$cpu -DSOC_CONFIG_${SOC_CONFIG} -DSYS_${SYS} $DEF_AVP $DEF_SEED - \
+ | \
+diff --git a/bsd/conf/Makefile b/bsd/conf/Makefile
+index 050f34a53c49..c58ff62cd419 100644
+--- a/bsd/conf/Makefile
++++ b/bsd/conf/Makefile
+@@ -17,6 +17,9 @@ MASTERCONFDIR = $(SRCROOT)/config
+ DOCONFDEPS = $(addprefix $(MASTERCONFDIR)/, MASTER MASTER.$(DOCONF_ARCH_CONFIG_LC)) \
+ $(addprefix $(SOURCE)/, Makefile.template Makefile.$(DOCONF_ARCH_CONFIG_LC) files files.$(DOCONF_ARCH_CONFIG_LC))
+
++# HakiOS: the drivers' choice (tools/hakios-config.py kernel); a new choice makes the configuration again
++DOCONFDEPS += $(wildcard $(MASTERCONFDIR)/MASTER.hakios)
++
+ ifneq (,$(wildcard $(MASTERCONFDIR)/MASTER.$(DOCONF_ARCH_CONFIG_LC).$(CURRENT_MACHINE_CONFIG_LC)))
+ DOCONFDEPS += $(MASTERCONFDIR)/MASTER.$(DOCONF_ARCH_CONFIG_LC).$(CURRENT_MACHINE_CONFIG_LC)
+ endif
diff --git a/bsd/conf/Makefile.arm64 b/bsd/conf/Makefile.arm64
index a4d25040f38f..aad72993d139 100644
--- a/bsd/conf/Makefile.arm64
@@ -62,58 +101,62 @@ index a4d25040f38f..aad72993d139 100644
kern_debug.o_INCFLAGS += -I$(SRCROOT)/osfmk
diff --git a/bsd/conf/files b/bsd/conf/files
-index 44274016a4cf..5f815c4379c0 100644
+index 44274016a4cf..086752d95378 100644
--- a/bsd/conf/files
+++ b/bsd/conf/files
-@@ -109,6 +109,47 @@ bsd/dev/munge.c optional config_requires_u32_munging
+@@ -109,6 +109,51 @@ bsd/dev/munge.c optional config_requires_u32_munging
bsd/dev/unix_startup.c standard
bsd/dev/monotonic.c optional monotonic
-+bsd/dev/hakios.input.c standard
-+bsd/dev/hakios.virtio_input.c standard
-+bsd/dev/hakios.goodix.c standard
-+bsd/dev/hakios.buttons.c standard
-+bsd/dev/hakios.battery.c standard
-+bsd/dev/hakios.ufs.c standard
-+bsd/dev/hakios.ufshc.c standard
-+bsd/dev/hakios.net.c standard
-+bsd/dev/hakios.ipa.c standard
-+bsd/dev/hakios.cell.c standard
-+bsd/dev/hakios.virtio_net.c standard
-+bsd/dev/hakios.apple80211.c standard
-+bsd/dev/hakios.cpufreq.c standard
-+bsd/dev/hakios.adreno.c standard
-+bsd/dev/hakios.audio.c standard
-+bsd/dev/hakios.virtio_sound.c standard
-+bsd/dev/hakios.speaker.c standard
-+bsd/dev/hakios.guard.c standard
-+bsd/dev/hakios.version.c standard
-+bsd/dev/hakios.haptic.c standard
-+bsd/dev/hakios.torch.c standard
-+bsd/dev/hakios.camera.c standard
-+bsd/dev/hakios.mic.c standard
-+bsd/dev/hakios.wifi.c standard
-+bsd/dev/hakios.adsp.c standard
-+bsd/dev/hakios.mpss.c standard
-+bsd/dev/hakios.image.c standard
-+bsd/dev/hakios.virtio_blk.c standard
-+bsd/dev/hakios.sparse.c standard
-+bsd/dev/hakios.apfs_check.c optional apfs
-+bsd/dev/hakios.sound.c standard
-+bsd/dev/hakios.qmi.c standard
-+bsd/dev/hakios.nas.c standard
-+bsd/dev/hakios.wlfw.c standard
-+bsd/dev/hakios.lx.c standard
-+bsd/dev/hakios.sta.c standard
-+bsd/dev/hakios.battguard.c standard
-+bsd/dev/hakios.pmic.c standard
-+bsd/dev/hakios.thermal.c standard
-+bsd/dev/hakios.bt.c standard
-+bsd/dev/hakios.socinfo.c standard
++# HakiOS drivers: made by tools/hakios-config.py kernel from drivers/*/conf. Edit those, not these lines.
++bsd/dev/hakios.audio.c standard
++bsd/dev/hakios.version.c standard
++bsd/dev/hakios.platform.c standard
++bsd/dev/hakios.stubs.c standard
++bsd/dev/hakios.input.c standard
++bsd/dev/hakios.net.c standard
++bsd/dev/hakios.image.c standard
++bsd/dev/hakios.sparse.c standard
++bsd/dev/hakios.apfs_check.c optional apfs
++bsd/dev/hakios.adsp.c optional hakios_adsp
++bsd/dev/hakios.speaker.c optional hakios_speaker
++bsd/dev/hakios.sound.c optional hakios_sound
++bsd/dev/hakios.guard.c optional hakios_sound
++bsd/dev/hakios.mic.c optional hakios_mic
++bsd/dev/hakios.virtio_sound.c optional hakios_virtio_sound
++bsd/dev/hakios.bt.c optional hakios_bt
++bsd/dev/hakios.camera.c optional hakios_camera
++bsd/dev/hakios.torch.c optional hakios_torch
++bsd/dev/hakios.socinfo.c optional hakios_socinfo
++bsd/dev/hakios.adreno.c optional hakios_adreno
++bsd/dev/hakios.haptic.c optional hakios_haptic
++bsd/dev/hakios.virtio_input.c optional hakios_virtio_input
++bsd/dev/hakios.goodix.c optional hakios_goodix
++bsd/dev/hakios.buttons.c optional hakios_buttons
++bsd/dev/hakios.qmi.c optional hakios_qmi
++bsd/dev/hakios.mpss.c optional hakios_modem
++bsd/dev/hakios.cell.c optional hakios_modem
++bsd/dev/hakios.nas.c optional hakios_modem
++bsd/dev/hakios.ipa.c optional hakios_modem
++bsd/dev/hakios.virtio_net.c optional hakios_virtio_net
++bsd/dev/hakios.battery.c optional hakios_battery
++bsd/dev/hakios.cpufreq.c optional hakios_cpufreq
++bsd/dev/hakios.thermal.c optional hakios_thermal
++bsd/dev/hakios.pmic.c optional hakios_pmic
++bsd/dev/hakios.battguard.c optional hakios_battguard
++bsd/dev/hakios.ufs.c optional hakios_ufs
++bsd/dev/hakios.ufshc.c optional hakios_ufs
++bsd/dev/hakios.virtio_blk.c optional hakios_virtio_blk
++bsd/dev/hakios.wifi.c optional hakios_wifi
++bsd/dev/hakios.wlfw.c optional hakios_wifi
++bsd/dev/hakios.lx.c optional hakios_wifi
++bsd/dev/hakios.sta.c optional hakios_wifi
++bsd/dev/hakios.apple80211.c optional hakios_wifi
++# end of the HakiOS drivers
bsd/dev/dev_perfmon.c optional config_perfmon
bsd/libkern/crc32.c standard
-@@ -155,6 +196,14 @@ bsd/miscfs/devfs/devfs_vfsops.c optional devfs
+@@ -155,6 +200,14 @@ bsd/miscfs/devfs/devfs_vfsops.c optional devfs
bsd/miscfs/mockfs/mockfs_fsnode.c optional mockfs
bsd/miscfs/mockfs/mockfs_vfsops.c optional mockfs
bsd/miscfs/mockfs/mockfs_vnops.c optional mockfs
@@ -128,7 +171,7 @@ index 44274016a4cf..5f815c4379c0 100644
bsd/miscfs/routefs/routefs_ops.c optional routefs
-@@ -361,6 +410,7 @@ bsd/security/audit/audit_syscalls.c standard
+@@ -361,6 +414,7 @@ bsd/security/audit/audit_syscalls.c standard
bsd/security/audit/audit_worker.c optional config_audit
bsd/pthread/pthread_shims.c standard
@@ -136,7 +179,7 @@ index 44274016a4cf..5f815c4379c0 100644
bsd/pthread/pthread_priority.c standard
bsd/pthread/pthread_workqueue.c standard
-@@ -383,6 +433,7 @@ bsd/kern/kern_debug.c standard
+@@ -383,6 +437,7 @@ bsd/kern/kern_debug.c standard
bsd/kern/kern_symfile.c standard
bsd/kern/kern_descrip.c standard
bsd/kern/kern_guarded.c standard
@@ -1479,7 +1522,7 @@ index 07147cb3188b..e937e62bf4c3 100644
options FDESC # fdesc_fs support # <fdesc>
options DEVFS # devfs support # <devfs>
diff --git a/config/MASTER.arm64.bcm2837 b/config/MASTER.arm64.bcm2837
-index 1ed75eea2052..54c5e12d2271 100644
+index 1ed75eea2052..117891784c1a 100644
--- a/config/MASTER.arm64.bcm2837
+++ b/config/MASTER.arm64.bcm2837
@@ -16,15 +16,15 @@
@@ -1513,6 +1556,21 @@ index 1ed75eea2052..54c5e12d2271 100644
# MACH_BASE = [ mach config_ecc_logging vc_progress_white importance_inheritance config_atm config_coalitions config_iosched config_library_validation config_sysdiagnose config_telemetry config_mach_bridge_recv_time config_quiesce_counter config_service_port_info ]
# MACH_RELEASE = [ MACH_BASE config_skip_precise_user_kernel_time debugger_for_zone_info ]
# MACH_DEV = [ MACH_BASE config_io_accounting importance_trace ]
+@@ -70,10 +70,10 @@
+ # SECURITY_DEV = [ SECURITY_BASE config_setuid config_kas_info ]
+ # SECURITY_DEBUG = [ SECURITY_BASE config_setuid config_kas_info ]
+ # BASE = [ MULTIPATH PF VPN ]
+-# RELEASE = [ BASE KERNEL_RELEASE BSD_RELEASE FILESYS_RELEASE SKYWALK_RELEASE NETWORKING_RELEASE IOKIT_RELEASE LIBKERN_RELEASE PERF_DBG_RELEASE MACH_RELEASE SCHED_RELEASE VM_RELEASE SECURITY_RELEASE ]
+-# DEVELOPMENT = [ BASE KERNEL_DEV BSD_DEV FILESYS_DEV NFS_DEV SKYWALK_DEV NETWORKING_DEV IOKIT_DEV LIBKERN_DEV PERF_DBG_DEV MACH_DEV SCHED_DEV VM_DEV SECURITY_DEV ]
+-# DEBUG = [ BASE KERNEL_DEBUG BSD_DEBUG FILESYS_DEBUG SKYWALK_DEBUG NETWORKING_DEBUG IOKIT_DEBUG LIBKERN_DEBUG PERF_DBG_DEBUG MACH_DEBUG SCHED_DEBUG VM_DEBUG SECURITY_DEBUG ]
+-# KASAN = [ BASE KERNEL_DEV BSD_DEV FILESYS_DEV NFS_DEV SKYWALK_DEV NETWORKING_DEV IOKIT_DEV LIBKERN_DEV PERF_DBG_DEV MACH_DEV SCHED_DEV VM_KASAN SECURITY_DEV ]
++# RELEASE = [ BASE KERNEL_RELEASE BSD_RELEASE FILESYS_RELEASE SKYWALK_RELEASE NETWORKING_RELEASE IOKIT_RELEASE LIBKERN_RELEASE PERF_DBG_RELEASE MACH_RELEASE SCHED_RELEASE VM_RELEASE SECURITY_RELEASE HAKIOS_DRIVERS ]
++# DEVELOPMENT = [ BASE KERNEL_DEV BSD_DEV FILESYS_DEV NFS_DEV SKYWALK_DEV NETWORKING_DEV IOKIT_DEV LIBKERN_DEV PERF_DBG_DEV MACH_DEV SCHED_DEV VM_DEV SECURITY_DEV HAKIOS_DRIVERS ]
++# DEBUG = [ BASE KERNEL_DEBUG BSD_DEBUG FILESYS_DEBUG SKYWALK_DEBUG NETWORKING_DEBUG IOKIT_DEBUG LIBKERN_DEBUG PERF_DBG_DEBUG MACH_DEBUG SCHED_DEBUG VM_DEBUG SECURITY_DEBUG HAKIOS_DRIVERS ]
++# KASAN = [ BASE KERNEL_DEV BSD_DEV FILESYS_DEV NFS_DEV SKYWALK_DEV NETWORKING_DEV IOKIT_DEV LIBKERN_DEV PERF_DBG_DEV MACH_DEV SCHED_DEV VM_KASAN SECURITY_DEV HAKIOS_DRIVERS ]
+ #
+ ######################################################################
+ #
diff --git a/iokit/Kernel/IOPMrootDomain.cpp b/iokit/Kernel/IOPMrootDomain.cpp
index 4a06407aea5f..2d2383953f7f 100644
--- a/iokit/Kernel/IOPMrootDomain.cpp
@@ -1729,25 +1787,56 @@ index 5219fb0d9ed6..29978e9cff43 100644
regEntry->release(); /* Toss the entry */
}
}
+diff --git a/iokit/conf/Makefile b/iokit/conf/Makefile
+index 83259ebf9835..8864e5c7cc41 100644
+--- a/iokit/conf/Makefile
++++ b/iokit/conf/Makefile
+@@ -16,6 +16,9 @@ endif
+ MASTERCONFDIR = $(SRCROOT)/config
+ DOCONFDEPS = $(addprefix $(MASTERCONFDIR)/, MASTER MASTER.$(DOCONF_ARCH_CONFIG_LC)) \
+ $(addprefix $(SOURCE)/, Makefile.template Makefile.$(DOCONF_ARCH_CONFIG_LC) files files.$(DOCONF_ARCH_CONFIG_LC))
++# HakiOS: the drivers' choice (tools/hakios-config.py kernel); a new choice makes the configuration again
++DOCONFDEPS += $(wildcard $(MASTERCONFDIR)/MASTER.hakios)
++
+ ifneq (,$(wildcard $(MASTERCONFDIR)/MASTER.$(DOCONF_ARCH_CONFIG_LC).$(CURRENT_MACHINE_CONFIG_LC)))
+ DOCONFDEPS += $(MASTERCONFDIR)/MASTER.$(DOCONF_ARCH_CONFIG_LC).$(CURRENT_MACHINE_CONFIG_LC)
+ endif
diff --git a/iokit/conf/files b/iokit/conf/files
-index 5fb0a52062e0..c07be8d9e0b0 100644
+index 5fb0a52062e0..7cfee3142b5b 100644
--- a/iokit/conf/files
+++ b/iokit/conf/files
-@@ -79,6 +79,14 @@ iokit/Kernel/IOSubMemoryDescriptor.cpp optional iokitcpp
+@@ -79,6 +79,17 @@ iokit/Kernel/IOSubMemoryDescriptor.cpp optional iokitcpp
iokit/Kernel/IOGuardPageMemoryDescriptor.cpp optional iokitcpp
iokit/Kernel/IOPlatformExpert.cpp optional iokitcpp
+iokit/Kernel/GenericARMPE.cpp optional iokitcpp
+iokit/Kernel/MiniIOSurface.cpp optional iokitcpp
+iokit/Kernel/MiniIOMobileFramebuffer.cpp optional iokitcpp
-+iokit/Kernel/hakios.gpu.cpp optional iokitcpp
-+iokit/Kernel/hakios.wlan.cpp optional iokitcpp
-+iokit/Kernel/hakios.battery.cpp optional iokitcpp
++# HakiOS drivers: made by tools/hakios-config.py kernel from drivers/*/conf. Edit those, not these lines.
++iokit/Kernel/hakios.stubs.cpp optional iokitcpp
++iokit/Kernel/hakios.gpu.cpp optional hakios_adreno iokitcpp
++iokit/Kernel/hakios.battery.cpp optional hakios_battery iokitcpp
++iokit/Kernel/hakios.wlan.cpp optional hakios_wifi iokitcpp
++# end of the HakiOS drivers
+iokit/Kernel/MiniAppleKeyStore.cpp optional iokitcpp
+iokit/Kernel/MiniIONetworkStack.cpp optional iokitcpp
iokit/Kernel/IOPlatformIO.cpp optional iokitcpp
iokit/Kernel/IOCPU.cpp optional iokitcpp
+diff --git a/libkern/conf/Makefile b/libkern/conf/Makefile
+index 050f34a53c49..c58ff62cd419 100644
+--- a/libkern/conf/Makefile
++++ b/libkern/conf/Makefile
+@@ -17,6 +17,9 @@ MASTERCONFDIR = $(SRCROOT)/config
+ DOCONFDEPS = $(addprefix $(MASTERCONFDIR)/, MASTER MASTER.$(DOCONF_ARCH_CONFIG_LC)) \
+ $(addprefix $(SOURCE)/, Makefile.template Makefile.$(DOCONF_ARCH_CONFIG_LC) files files.$(DOCONF_ARCH_CONFIG_LC))
+
++# HakiOS: the drivers' choice (tools/hakios-config.py kernel); a new choice makes the configuration again
++DOCONFDEPS += $(wildcard $(MASTERCONFDIR)/MASTER.hakios)
++
+ ifneq (,$(wildcard $(MASTERCONFDIR)/MASTER.$(DOCONF_ARCH_CONFIG_LC).$(CURRENT_MACHINE_CONFIG_LC)))
+ DOCONFDEPS += $(MASTERCONFDIR)/MASTER.$(DOCONF_ARCH_CONFIG_LC).$(CURRENT_MACHINE_CONFIG_LC)
+ endif
diff --git a/libkern/conf/files b/libkern/conf/files
index ece14c7d41d3..4a903f73a9ef 100644
--- a/libkern/conf/files
@@ -1774,6 +1863,20 @@ index 28ea44c2ae9d..9c7a1fe9e23e 100644
"only plain data types can be contained (consider using OSValueObject)");
return 0; // C++11 does not support void-returning constexpr functions
}
+diff --git a/libsa/conf/Makefile b/libsa/conf/Makefile
+index 050f34a53c49..c58ff62cd419 100644
+--- a/libsa/conf/Makefile
++++ b/libsa/conf/Makefile
+@@ -17,6 +17,9 @@ MASTERCONFDIR = $(SRCROOT)/config
+ DOCONFDEPS = $(addprefix $(MASTERCONFDIR)/, MASTER MASTER.$(DOCONF_ARCH_CONFIG_LC)) \
+ $(addprefix $(SOURCE)/, Makefile.template Makefile.$(DOCONF_ARCH_CONFIG_LC) files files.$(DOCONF_ARCH_CONFIG_LC))
+
++# HakiOS: the drivers' choice (tools/hakios-config.py kernel); a new choice makes the configuration again
++DOCONFDEPS += $(wildcard $(MASTERCONFDIR)/MASTER.hakios)
++
+ ifneq (,$(wildcard $(MASTERCONFDIR)/MASTER.$(DOCONF_ARCH_CONFIG_LC).$(CURRENT_MACHINE_CONFIG_LC)))
+ DOCONFDEPS += $(MASTERCONFDIR)/MASTER.$(DOCONF_ARCH_CONFIG_LC).$(CURRENT_MACHINE_CONFIG_LC)
+ endif
diff --git a/makedefs/MakeInc.cmd b/makedefs/MakeInc.cmd
index bc39e19b3b8e..0a72a2d43908 100644
--- a/makedefs/MakeInc.cmd
@@ -2730,6 +2833,20 @@ index e5336e5a1cce..a54e35035cde 100644
#if !VMAPPLE
MOV64 x1, SCTLR_EL1_DEFAULT
+diff --git a/osfmk/conf/Makefile b/osfmk/conf/Makefile
+index 050f34a53c49..c58ff62cd419 100644
+--- a/osfmk/conf/Makefile
++++ b/osfmk/conf/Makefile
+@@ -17,6 +17,9 @@ MASTERCONFDIR = $(SRCROOT)/config
+ DOCONFDEPS = $(addprefix $(MASTERCONFDIR)/, MASTER MASTER.$(DOCONF_ARCH_CONFIG_LC)) \
+ $(addprefix $(SOURCE)/, Makefile.template Makefile.$(DOCONF_ARCH_CONFIG_LC) files files.$(DOCONF_ARCH_CONFIG_LC))
+
++# HakiOS: the drivers' choice (tools/hakios-config.py kernel); a new choice makes the configuration again
++DOCONFDEPS += $(wildcard $(MASTERCONFDIR)/MASTER.hakios)
++
+ ifneq (,$(wildcard $(MASTERCONFDIR)/MASTER.$(DOCONF_ARCH_CONFIG_LC).$(CURRENT_MACHINE_CONFIG_LC)))
+ DOCONFDEPS += $(MASTERCONFDIR)/MASTER.$(DOCONF_ARCH_CONFIG_LC).$(CURRENT_MACHINE_CONFIG_LC)
+ endif
diff --git a/osfmk/conf/files b/osfmk/conf/files
index 9d98c50094a0..9e3476124e54 100644
--- a/osfmk/conf/files
@@ -3148,6 +3265,20 @@ index 65144c74239c..ab6260d52d84 100644
uart_putc(c);
}
+diff --git a/pexpert/conf/Makefile b/pexpert/conf/Makefile
+index 050f34a53c49..c58ff62cd419 100644
+--- a/pexpert/conf/Makefile
++++ b/pexpert/conf/Makefile
+@@ -17,6 +17,9 @@ MASTERCONFDIR = $(SRCROOT)/config
+ DOCONFDEPS = $(addprefix $(MASTERCONFDIR)/, MASTER MASTER.$(DOCONF_ARCH_CONFIG_LC)) \
+ $(addprefix $(SOURCE)/, Makefile.template Makefile.$(DOCONF_ARCH_CONFIG_LC) files files.$(DOCONF_ARCH_CONFIG_LC))
+
++# HakiOS: the drivers' choice (tools/hakios-config.py kernel); a new choice makes the configuration again
++DOCONFDEPS += $(wildcard $(MASTERCONFDIR)/MASTER.hakios)
++
+ ifneq (,$(wildcard $(MASTERCONFDIR)/MASTER.$(DOCONF_ARCH_CONFIG_LC).$(CURRENT_MACHINE_CONFIG_LC)))
+ DOCONFDEPS += $(MASTERCONFDIR)/MASTER.$(DOCONF_ARCH_CONFIG_LC).$(CURRENT_MACHINE_CONFIG_LC)
+ endif
diff --git a/pexpert/pexpert/arm64/BCM2837.h b/pexpert/pexpert/arm64/BCM2837.h
index d9f0723244e5..53fe4f371d7f 100644
--- a/pexpert/pexpert/arm64/BCM2837.h
@@ -3203,6 +3334,34 @@ index c84b2100bc19..aaad5cd2e8c6 100644
#define MAX_CPU_CLUSTERS 1
#define CORE_NCTRS 8 /* Placeholder; KPC is not enabled for this target */
+diff --git a/san/conf/Makefile b/san/conf/Makefile
+index 050f34a53c49..c58ff62cd419 100644
+--- a/san/conf/Makefile
++++ b/san/conf/Makefile
+@@ -17,6 +17,9 @@ MASTERCONFDIR = $(SRCROOT)/config
+ DOCONFDEPS = $(addprefix $(MASTERCONFDIR)/, MASTER MASTER.$(DOCONF_ARCH_CONFIG_LC)) \
+ $(addprefix $(SOURCE)/, Makefile.template Makefile.$(DOCONF_ARCH_CONFIG_LC) files files.$(DOCONF_ARCH_CONFIG_LC))
+
++# HakiOS: the drivers' choice (tools/hakios-config.py kernel); a new choice makes the configuration again
++DOCONFDEPS += $(wildcard $(MASTERCONFDIR)/MASTER.hakios)
++
+ ifneq (,$(wildcard $(MASTERCONFDIR)/MASTER.$(DOCONF_ARCH_CONFIG_LC).$(CURRENT_MACHINE_CONFIG_LC)))
+ DOCONFDEPS += $(MASTERCONFDIR)/MASTER.$(DOCONF_ARCH_CONFIG_LC).$(CURRENT_MACHINE_CONFIG_LC)
+ endif
+diff --git a/security/conf/Makefile b/security/conf/Makefile
+index 2efc18a7a9d6..04fc48e02ccb 100644
+--- a/security/conf/Makefile
++++ b/security/conf/Makefile
+@@ -17,6 +17,9 @@ MASTERCONFDIR = $(SRCROOT)/config
+ DOCONFDEPS = $(addprefix $(MASTERCONFDIR)/, MASTER MASTER.$(DOCONF_ARCH_CONFIG_LC)) \
+ $(addprefix $(SOURCE)/, Makefile.template Makefile.$(DOCONF_ARCH_CONFIG_LC) files files.$(DOCONF_ARCH_CONFIG_LC))
+
++# HakiOS: the drivers' choice (tools/hakios-config.py kernel); a new choice makes the configuration again
++DOCONFDEPS += $(wildcard $(MASTERCONFDIR)/MASTER.hakios)
++
+ ifneq (,$(wildcard $(MASTERCONFDIR)/MASTER.$(DOCONF_ARCH_CONFIG_LC).$(CURRENT_MACHINE_CONFIG_LC)))
+ DOCONFDEPS += $(MASTERCONFDIR)/MASTER.$(DOCONF_ARCH_CONFIG_LC).$(CURRENT_MACHINE_CONFIG_LC)
+ endif
diff --git a/security/mac_vfs_subr.c b/security/mac_vfs_subr.c
index 97028c06bb92..0daad830d0c0 100644
--- a/security/mac_vfs_subr.c
diff --git a/xnu/sync-drivers.sh b/xnu/sync-drivers.sh
index 46bf3c5..0ccb539 100755
--- a/xnu/sync-drivers.sh
+++ b/xnu/sync-drivers.sh
@@ -21,4 +21,17 @@ while read -r sub tree _; do
copied=$((copied + 1))
fi
done < "$HERE/../drivers/map"
+# ... and the drivers of the SoC and device repositories checked out (socs/*/drivers/, devices/*/drivers/: docs/porting/repositories.md)
+while IFS="$(printf '\t')" read -r src tree; do
+ [ -n "$src" ] || continue
+ [ -f "$src" ] || { echo "sync-drivers: $src is named by its repository's conf but missing" >&2; exit 1; }
+ if [ ! -e "$TREE/$tree" ] || { [ "$src" -nt "$TREE/$tree" ] && ! cmp -s "$src" "$TREE/$tree"; }; then
+ mkdir -p "$(dirname "$TREE/$tree")"
+ cp -p "$src" "$TREE/$tree"
+ echo "sync-drivers: ${src#$HERE/../} -> $tree"
+ copied=$((copied + 1))
+ fi
+done <<EOF2
+$(python3 "$HERE/../tools/hakios-config.py" external-files)
+EOF2
[ "$copied" -gt 0 ] || echo "sync-drivers: drivers in step with the kernel tree"
diff --git a/xnuloader/loader.c b/xnuloader/loader.c
index d120105..87ed0ff 100644
--- a/xnuloader/loader.c
+++ b/xnuloader/loader.c
@@ -4238,7 +4238,7 @@ print_banner(void)
print(" # # # # # # # # # #\n");
print(" # # # # # # ##### ### ####\n");
print("\n");
- print(" hello hackios-kernel!\n");
+ print(" hello hakios-kernel!\n");
print(" kernel.ver=%s\n", version ? version : "unknown");
print("\n");
}