Apple's open-source XNU kernel on Android phones: its own loader and drivers, Metal on the Adreno. Runs from RAM; a reboot gives the phone back to Android.
C
docs: configurations and the kernel's version, written from the tools as they are
shimoku31622bb430fc
diff --git a/docs/configs.md b/docs/configs.mdnew file mode 100644index 0000000..af71cda--- /dev/null+++ b/docs/configs.md@@ -0,0 +1,84 @@+# Configurations: defconfigs, fragments and a `.config`++A Linux kernel is configured with a `.config` made from a `<device>_defconfig` (`make redwood_defconfig`), and an+Android kernel adds fragments on top (`merge_config.sh`). 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.++```+configs/defconfig what every configuration starts from: the OPEN one (nothing of a phone's own, one core)+configs/redwood_defconfig the POCO X5 Pro 5G (redwood, SM7325): what the project's own phone line uses+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+configs/persist.config fragment: keep /private/var across reboots (THIS WRITES TO THE PHONE, partition `darwin`)+```++## Use++```bash+make redwood_defconfig # .config = configs/defconfig + configs/redwood_defconfig+make redwood_defconfig FRAGMENTS=trace # ... and a fragment on top+make virt.config # lay a fragment over the .config there is+make config # show it: symbols, the kernel's arguments, the firmware it wants+make savedefconfig # the .config as a minimal defconfig (what differs from configs/defconfig)+make phone # with a .config, ITS arguments are the kernel's+```++The same without make: `tools/hakios-config.py defconfig|merge|args|check|show|needs|savedefconfig|list|help`.+`tools/hakios-config.py help GPU` says what a symbol means, what it needs and what it requires. `make doctor`+checks the host.++## What a symbol is++`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`.++The table of symbols is the `SYMBOLS` list at the top of `tools/hakios-config.py`; it is the one place that says+which symbol is which argument.++## What is checked, and why++- **Types and ranges.** A bool is `y` or not set, a hex number starts with `0x`, `CONFIG_CPUS` is 1 to 8. A typo in+ a name gets a suggestion (`no symbol CONFIG_GPUU (did you mean CONFIG_GPU?)`).+- **Dependencies.** `CONFIG_VAR_STORE` requires `CONFIG_UFS_WRITE`, which requires `CONFIG_UFS=2`; `CONFIG_SOUND`+ requires `CONFIG_ADSP`; the modem requires the storage service.+- **Firmware.** `CONFIG_FIRMWARE="none"` is the open profile: *nothing of the phone's own is loaded.* The check refuses+ a configuration that says `none` and still asks for the GPU, Wi-Fi, audio, haptics, cameras or the modem, because each+ of those uses firmware pulled from the owner's own phone (`fw-*/`, never in this repository).+- **The command line fits.** The kernel's boot line holds 607 characters, and a longer one loses its tail without an+ error. The check counts the arguments, adds what a run adds itself (about 260) and refuses what cannot fit.++## `CONFIG_BOOTARGS`: Linux's `CONFIG_CMDLINE`++For an argument that has no symbol of its own: `CONFIG_BOOTARGS="fb_beat=2 loader_return_after=5"`. It is not an+escape from the checks. Every name must be one the source reads ([boot-args.md](boot-args.md), made by+`tools/boot-args.py` from the code, and checked in CI), so `fb_beet=2` is an error with a suggestion rather than a+silent no-op; an argument that a symbol already sets (`cpus=8`) is refused with the name of the symbol; a word is+`name=value` with no space, quote or backslash in it; and the words count towards the 607 characters.++## What is the same as Linux, and what is not++| | Linux / Android | here |+|---|---|---|+| a device | `arch/arm64/configs/<device>_defconfig` | `configs/<device>_defconfig` |+| a fragment | `kernel/configs/*.config`, `merge_config.sh` | `configs/*.config`, `make NAME.config` |+| the result | `.config`, compiled in | `.config`, becomes the boot-arguments |+| 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=` |++## A new device++`tools/new-device.py` makes `devices/<name>/` from a phone's own device tree; its defconfig is a file of a few+lines, `configs/<name>_defconfig`, that starts from the open one and turns on only what that phone has been shown+to do.++## 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)+and the tests say, and the project does not claim a result it has not seen.diff --git a/docs/versioning.md b/docs/versioning.mdnew file mode 100644index 0000000..d03e454--- /dev/null+++ b/docs/versioning.md@@ -0,0 +1,65 @@+# The kernel's version++An Android kernel says `5.4.147-android12-9-...-g1a2b3c4d`: the Linux it is built on, the vendor's branch, and the+commit. This kernel says the same kind of thing about itself:++```+2.1.13-hakios-darwin22.5-sc7280-g1a2b3c4d[-dirty]+│ │ │ │ │ │ └ the commit; "-dirty" if a tracked file differs from it+│ │ │ │ │ └ the SoC family the configuration is for (CONFIG_SOC)+│ │ │ │ └ the Darwin it is built on (22.5.0, Apple's open xnu-8796.121.2)+│ │ │ └ EXTRAVERSION: what the tree is called+│ │ └ SUBLEVEL+│ └ PATCHLEVEL+└ VERSION+```++## Where it is shown++1. **The loader's banner** (`xnuloader/`), under `HAKIOS`: `hello hackios-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.++Darwin's own `uname -v` ("Darwin Kernel Version 22.5.0: ...") is Apple's and stays as it is, as Linux's `uname -r` stays+in an Android kernel next to the vendor's own string.++## Where it comes from++`VERSION`, at the top of the repository, in the form of the Makefile of Linux (`VERSION`, `PATCHLEVEL`, `SUBLEVEL`,+`EXTRAVERSION`, `NAME`, plus `DARWIN` and `XNU`: the release this port sits on). `tools/kernel-version.py` makes the+string from it, from `CONFIG_SOC` of the `.config` (see [configs.md](configs.md)) and from git:++```bash+tools/kernel-version.py # 2.1.13-hakios-darwin22.5-sc7280-g1a2b3c4d (the -sc7280 part is there with a .config)+tools/kernel-version.py --short # 2.1.13+tools/kernel-version.py --release # 2.1.13-hakios: what a tag is called (v2.1.13-hakios)+tools/kernel-version.py --all # every part, for a build log+```++`HAKIOS_VERSION_SUFFIX` in the environment replaces the git part (a reproducible build, or a tree that is not a+checkout).++The kernel is told its version and does not carry it, on purpose: it is built once from Apple's open source plus this+port, and the payload is made in a second. A version that is only the commit, or the SoC of one configuration, then does+not need the Mach-O rebuilt.++## When a number moves++| | moves when | example |+|---|---|---|+| **VERSION** (2) | a change that breaks what a user, a port or a boot image relies on | the payload format, the meaning of a boot-argument, the layout of the partition `darwin` |+| **PATCHLEVEL** (1) | a feature | a driver, a device, a tool |+| **SUBLEVEL** (13) | a fix | a bug in a driver, a wrong default |+| **EXTRAVERSION** | the tree is somebody's branch | a vendor writes its own here, as Android's `-android12-9` |++A boot-argument that is removed or changes its meaning is a **VERSION** change, which is why+[boot-args.md](boot-args.md) is made from the source and checked in CI: it is the list of what a version promises.++## Honest limits++- The number says which source the kernel was built from. It does not say that any given phone boots it; what has+ been seen to boot is in the README's status table and in [port-pkg110.md](port-pkg110.md).+- `-dirty` means a tracked file differs from the commit. A build from a modified tree says so.+- `Darwin 22.5` is a name for the open-source xnu release the kernel is built on. The kernel is not Apple's `kernel`+ and is not iOS's.