Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/checks.yml
Original file line number Diff line number Diff line change
Expand Up @@ -45,9 +45,9 @@ jobs:
steps:
- name: Packages the tests use
run: |
pacman -Syu --noconfirm --needed git base-devel e2fsprogs zstd openssl \
pacman -Syu --noconfirm --needed git base-devel e2fsprogs zstd lz4 openssl \
python python-dbus python-gobject dbus nodejs dtc cpio file jq busybox \
xz gzip qt6-declarative shellcheck rsync
xz gzip qt6-declarative shellcheck rsync android-tools
# Arch's nodejs can lag a simdjson soname bump: on 2026-10-29
# simdjson 5.0.8 dropped the libsimdjson.so.34 that nodejs still
# linked, and node no longer started. Only while node can't start,
Expand Down
4 changes: 2 additions & 2 deletions docs/INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,10 @@ Today these steps are manual. Where the install is going, one guided step from a

- **A Pixel 7 Pro** whose bootloader can be unlocked. Phones sold locked to a carrier often can't be. In Android, go to Settings > About phone and tap Build number seven times to turn on Developer options, then check that Settings > System > Developer options > **OEM unlocking** can be switched on. If it's greyed out, the phone can't be unlocked.
- **A computer running Linux** (Omarchy, Arch Linux or another distribution), and a USB-C cable that carries data. The installer is a shell script for Linux; installing from a web page or a desktop app is planned.
- **These programs on the computer:** `fastboot` and `adb` (Android platform tools), `e2fsprogs`, `zstd`, `openssl`, `gnupg`, `python3`, `unzip`, and `binutils`. On Omarchy or Arch Linux:
- **These programs on the computer:** `fastboot` and `adb` (Android platform tools), `e2fsprogs`, `zstd`, `lz4`, `cpio`, `openssl`, `gnupg`, `python3`, `unzip`, and `binutils`. On Omarchy or Arch Linux:

```sh
sudo pacman -S --needed android-tools e2fsprogs zstd openssl gnupg python unzip binutils erofs-utils
sudo pacman -S --needed android-tools e2fsprogs zstd lz4 cpio openssl gnupg python unzip binutils erofs-utils
```

On other distributions, install the packages with the same names (Android's tools are often split into `fastboot`, `adb` and a "libsparse" package for `img2simg` and `simg2img`).
Expand Down
6 changes: 3 additions & 3 deletions docs/RELEASES.md
Original file line number Diff line number Diff line change
Expand Up @@ -183,7 +183,7 @@ As built (§5.5), the tool and the hook are their own package, `omamobile-boot-u

The same Alpine-based initramfs, with release differences:

- **No developer keys.** It ships without `authorized_keys`: `bin/omamobile initramfs --release` builds it that way, and `tools/make-bundle` refuses to sign a bundle whose initramfs still holds SSH keys. The hook appends a second, tiny cpio to the ramdisk that holds the phone's own `/root/.ssh/authorized_keys` (the kernel unpacks concatenated cpio archives in order), so SSH into the initramfs keeps working for the phone's owner and nobody else.
- **No developer keys.** It ships without `authorized_keys`: `bin/omamobile initramfs --release` builds it that way, and `tools/make-bundle` refuses to sign a bundle whose initramfs still holds SSH keys. The hook appends a second, tiny cpio to the ramdisk that holds the phone's own `/root/.ssh/authorized_keys` (the kernel unpacks concatenated cpio archives in order), so SSH into the initramfs keeps working for the phone's owner and nobody else. `tools/install-phone` appends the same cpio, with the same commands, to a copy of the bundle's ramdisk image (`vendor_kernel_boot`, or `vendor_boot` on a phone without one) before flashing it, so the initramfs takes the owner's key from the first boot and the hook's first run finds the image it would build already on slot B (`tests/install-phone-initramfs`). A device with `INITRAMFS_MODULES` (raven) is the exception: the hook's cpio also carries those modules, so its first run rewrites the image once.
- **No bring-up probes.** `probe()` and `omamobile.debug` stay in development builds only.
- **Quirks from the descriptor.** The trigger write is already per device: `bin/omamobile initramfs` packs `SIMPLEFB_TRIG_CON` into `/etc/omamobile-simplefb-trig` and `COMPATIBLE` beside it. The init writes the pair only when the board's first compatible string matches. A device without the trigger key gets no register write. The storage guard's allowlist is packed the same way, from `UFS_RW` into `/etc/omamobile-ufs-rw`, and the init leaves every partition read-only without a valid one. So is the USB product string (`USB_PRODUCT`, else `NAME`). Step 2 still turns the remaining quirk (`MAIN_LUN`) into a generated `/etc/omamobile/device.conf` the shared init reads at boot. That remaining step changes what boots, so it gets its own runbook and a test boot from `bin/omamobile push`; it is not a refactor.
- **Reproducible:** fixed mtimes (`SOURCE_DATE_EPOCH`), sorted file list, `cpio --reproducible`.
Expand Down Expand Up @@ -323,9 +323,9 @@ The bundle's signed `SHA256SUMS` covers its `MANIFEST`, which names the exact ro

1. Checks the bundle's signature and checksums, and that `fastboot getvar product` is this bundle's codename, the bootloader is unlocked, and both slots carry the same bootloader version. Any doubt stops it.
2. Asks for the user's factory zip, checks its `board=`, and runs the device's firmware and chroot extraction on the laptop.
3. Makes a **local copy** of the root image and writes into it, with `debugfs -w` (no root needed): the extracted firmware, the user's SSH public key, `/etc/omamobile/boot-update.conf` with `AUTO_WRITE=yes`, and a first-boot marker naming the device package to install. Nothing extracted leaves the laptop except into the user's own phone.
3. Makes a **local copy** of the root image and writes into it, with `debugfs -w` (no root needed): the extracted firmware, the user's SSH public key, `/etc/omamobile/boot-update.conf` with `AUTO_WRITE=yes`, and a first-boot marker naming the device package to install. The same key goes into a local copy of the ramdisk image's initramfs, as the boot hook appends it (§5.2), and that copy is what step 5 flashes. Nothing extracted leaves the laptop except into the user's own phone.
4. Shows exactly what it will write (`BOOT_IMAGES` with `_b`, and `userdata`), says that `userdata` is erased (stock Android needs a factory reset if it is ever booted again), and waits for the user to type the codename.
5. Runs only `fastboot flash <image>_b images/<image>.img` for each `BOOT_IMAGES` entry, `fastboot flash userdata <root image>`, `fastboot --set-active=b` and `fastboot reboot`. The partition names come from the descriptor and are checked against its `UFS_RW` again; the script has no code path for any other partition, no `-w`, no `--slot`, no `flashing` command.
5. Runs only `fastboot flash <image>_b images/<image>.img` for each `BOOT_IMAGES` entry (the ramdisk image from its copy, step 3), `fastboot flash userdata <root image>`, `fastboot --set-active=b` and `fastboot reboot`. The partition names come from the descriptor and are checked against its `UFS_RW` again; the script has no code path for any other partition, no `-w`, no `--slot`, no `flashing` command.
6. On first boot, `omamobile-setup-system` installs the device package named by the marker (from the package cache, offline) and reminds the user to take the read-only backup of `efs`, `efs_backup`, `modem_userdata`, `persist` and `modem_a/b` ([MODEM-PLAN](../device/cheetah/MODEM-PLAN.md) M0.1) before any radio work. `tools/nv-backup DIR` (in the bundle's `tools/`) takes it over USB SSH: the partitions from the descriptor's `NV_PARTS` and `NV_BACKUP_EXTRA`, found by `PARTNAME`, refused unless every one is found once, read-only and unmounted, each copied with `dd`, read again on the phone and compared, into a directory of mode 700 with files of mode 600; `--check DIR` compares the phone with it later.

`bin/omamobile flash` stays the developer's tool; `install` is for everyone else and is deliberately narrower.
Expand Down
5 changes: 3 additions & 2 deletions tests/all
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
#!/bin/bash
# SPDX-License-Identifier: MIT
# The installer's tests (no phone, nothing flashed): tools/install-phone
# against a fake fastboot, tools/phone-provision against a synthetic backup
# against a fake fastboot (and the ramdisk image it flashes against the one
# omamobile-boot-update builds), tools/phone-provision against a synthetic backup
# (and a container standing in for the phone, with Docker), tools/nv-backup
# against a stand-in phone tree,
# tools/phone-install-package against a stand-in phone, the initramfs's
Expand Down Expand Up @@ -44,7 +45,7 @@ sh -n device/flame/initramfs/build
bash -n tools/build-flame-probe
echo "ok - scripts parse"
python3 tests/bt-uart-gpio.py
for t in tests/pr-check tests/kernel-pr-check tests/phone-smoke tests/alarm-wake-test tests/install-phone tests/build-rootfs tests/rootfs-resolve tests/phone-provision tests/nv-backup tests/initramfs-grow tests/images-layout tests/boot-update-parity tests/stage-boot-files tests/initramfs-reproducible tests/device-overlays tests/simplefb-trigger tests/initramfs-steps tests/storage-guard tests/usb-product tests/grep-q-pipes tests/boot-method tests/modules-push tests/make-bundle-keys tests/make-bundle tests/release-signing tests/pinned-packages tests/flame-probe packages/omamobile-firstboot/test/all packages/omamobile-device-felix/test/all packages/omamobile-device-lynx/test/all packages/omamobile-device-panther/test/all tests/local-builds tests/phone-install-package tests/publish-kernel tests/fetch-toolchain tests/release-upload tests/extract-camera-data tests/release tests/lineage-ref tests/repo-publish tests/repo-publish-stage tests/extract-vendor-firmware tests/alpine-fetch-callers tests/alpine-fetch tests/tools-help; do
for t in tests/pr-check tests/kernel-pr-check tests/phone-smoke tests/alarm-wake-test tests/install-phone tests/build-rootfs tests/rootfs-resolve tests/phone-provision tests/nv-backup tests/initramfs-grow tests/images-layout tests/boot-update-parity tests/stage-boot-files tests/initramfs-reproducible tests/device-overlays tests/simplefb-trigger tests/initramfs-steps tests/storage-guard tests/usb-product tests/grep-q-pipes tests/boot-method tests/modules-push tests/make-bundle-keys tests/make-bundle tests/release-signing tests/pinned-packages tests/flame-probe packages/omamobile-firstboot/test/all packages/omamobile-device-felix/test/all packages/omamobile-device-lynx/test/all packages/omamobile-device-panther/test/all tests/local-builds tests/phone-install-package tests/publish-kernel tests/fetch-toolchain tests/release-upload tests/extract-camera-data tests/release tests/lineage-ref tests/repo-publish tests/repo-publish-stage tests/extract-vendor-firmware tests/alpine-fetch-callers tests/alpine-fetch tests/tools-help tests/install-phone-initramfs; do
echo "# $t"
"$t"
done
Expand Down
22 changes: 18 additions & 4 deletions tests/install-phone
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.."
SRC=$PWD
fail() { printf 'not ok - %s\n' "$1" >&2; exit 1; }
pass() { printf 'ok - %s\n' "$1"; }
for tool in debugfs mkfs.ext4 zstd openssl; do command -v $tool >/dev/null || { echo "skip: no $tool"; exit 0; }; done
for tool in debugfs mkfs.ext4 zstd openssl lz4 cpio; do command -v $tool >/dev/null || { echo "skip: no $tool"; exit 0; }; done
t=$(mktemp -d)
cleanup() {
[[ ! -d $t/gnupg ]] || gpgconf --homedir "$t/gnupg" --kill gpg-agent 2>/dev/null || true
Expand All @@ -34,7 +34,21 @@ UFS_RW="boot_b init_boot_b vendor_boot_b vendor_kernel_boot_b dtbo_b userdata"
EOF
}
descriptor > "$R/device/testdev/device.conf"
for p in boot init_boot vendor_boot vendor_kernel_boot dtbo vbmeta; do echo "$p image" > "$t/images/$p.img"; done
for p in boot init_boot dtbo vbmeta; do echo "$p image" > "$t/images/$p.img"; done
# The ramdisk image is a real v4 vendor boot image (install-phone appends the
# owner's key to its initramfs; tests/install-phone-initramfs checks the bytes)
mkdir -p "$t/rd/etc" && echo init > "$t/rd/init"
(cd "$t/rd" && find . | LC_ALL=C sort | cpio -o -H newc --quiet) | lz4 -l -9 -q > "$t/rd.lz4"
for p in vendor_boot vendor_kernel_boot; do
python3 -I -c '
import struct, sys
rd, page = open(sys.argv[1], "rb").read(), 4096
pad = lambda b: b + bytes(-len(b) % page)
hdr = struct.pack("<8s5I2048sI16s2IQ4I", b"VNDRBOOT", 4, page, 0, 0, len(rd), b"", 0, b"", 2128, 3, 0, 108, 1, 108, 0)
table = struct.pack("<3I32s", len(rd), 0, 1, b"") + bytes(64)
open(sys.argv[2], "wb").write(pad(hdr) + pad(rd) + pad(b"dtb") + pad(table))
' "$t/rd.lz4" "$t/images/$p.img"
done
echo testdev > "$t/images/DEVICE"
echo 'root:x:0:0::/root:/bin/bash' > "$t/rootdir/etc/passwd"
mkfs.ext4 -q -L omamobile-root -d "$t/rootdir" "$t/root.img" 16M
Expand Down Expand Up @@ -91,7 +105,7 @@ install --dry-run || { cat "$t/out"; fail "a dry run succeeds"; }
expected=" would run: fastboot -s FAKE123 flash boot_b $t/images/boot.img
would run: fastboot -s FAKE123 flash init_boot_b $t/images/init_boot.img
would run: fastboot -s FAKE123 flash vendor_boot_b $t/images/vendor_boot.img
would run: fastboot -s FAKE123 flash vendor_kernel_boot_b $t/images/vendor_kernel_boot.img
would run: fastboot -s FAKE123 flash vendor_kernel_boot_b $t/work/ramdisk/vendor_kernel_boot.img
would run: fastboot -s FAKE123 flash dtbo_b $t/images/dtbo.img
would run: fastboot -s FAKE123 flash userdata $t/work/root.simg
would run: fastboot -s FAKE123 --set-active=b
Expand All @@ -115,7 +129,7 @@ install || { cat "$t/out"; fail "a full run succeeds"; }
want="-s FAKE123 flash boot_b $t/images/boot.img
-s FAKE123 flash init_boot_b $t/images/init_boot.img
-s FAKE123 flash vendor_boot_b $t/images/vendor_boot.img
-s FAKE123 flash vendor_kernel_boot_b $t/images/vendor_kernel_boot.img
-s FAKE123 flash vendor_kernel_boot_b $t/work/ramdisk/vendor_kernel_boot.img
-s FAKE123 flash dtbo_b $t/images/dtbo.img
-s FAKE123 flash userdata $t/work/root.simg
-s FAKE123 --set-active=b
Expand Down
Loading