Skip to content
Open
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
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Omarchy Mobile runs native Omarchy (Arch Linux ARM, Hyprland, Omarchy's packages
- **`tools/install-phone`, and the installer `omamobile-install` under the same rules, change the bootloader's slot flags in two named cases.** `bin/omamobile flash`'s `--set-active=b` and the boot-success mark (`omamobile-boot-success`) stay as they are; nothing else gains one. The first is its `fastboot --set-active=b` after the writes. The second is a round trip that reads the other slot's bootloader version where the bootloader reports only the current slot's ([INSTALL-EXPERIENCE-PLAN](docs/INSTALL-EXPERIENCE-PLAN.md) G4, D4, decided 2026-11-10): `--set-active=<other>`, `reboot bootloader`, read `version-bootloader`, `--set-active=<first>`, `reboot bootloader`, check. It is off unless the device's descriptor says `BOOTLOADER_SLOT_PROBE=yes`, a line the maintainer adds after an attended run on that device is in its notes; no device has the line, and the round trip has not run on any phone. It runs only through `tools/install-phone` (which `tools/install-guided` calls with the owner's yes) and `omamobile-install` (derekross/omamobile-installer: its `install --write`, `json --write` and the web page's write preview; never a dry run and never the page that ships; the descriptor line read from the release's signed `device.conf`, and the device on its own list, which no Qualcomm phone is on), and only on what the tool can see of a first install: the phone on slot A, no `--reinstall`, slot B not reading as a slot that has started and can still start (`slot-successful` yes with `slot-unbootable` no: that is an installed Omarchy Mobile sent back to slot A, and also stock after a system update, and fastboot can't tell them apart), and the owner's yes, typed on a terminal or passed by the calling tool as `--measure-other-slot`. It flashes and erases nothing, but it is a write: the bootloader keeps the slot flags in its own storage (`devinfo` on our Pixels), and both slots' flags change. Stock's slot A may lose its successful mark and, once the install has taken `userdata`, may never earn it back; what that costs is not measured. It also starts the other slot's bootloader before its version is known, which is what the check exists to prevent: [Google's factory images page](https://developers.google.com/android/images) warns that on the Pixel 6, Pixel 8 and Pixel 10 families an older bootloader in the inactive slot can leave the phone unbootable, so a phone of those families gets the line only by the maintainer's separate decision. If a step fails while the phone still answers, the installer sets the first slot active again; a phone not seen to leave the bus and come back gets nothing more, and the owner gets the buttons and the command, which are also printed before the question. It never runs with `--reinstall`: `--set-active` clears a slot's successful mark, which with slot B ours costs boot tries on the Pixel 9a and can end in a fallback that erases `userdata` (boot chain notes below; on the 9a, ask the maintainer before any fastboot write to slot B, a first install's included). The installer can't see what is on slot B, so pass `--reinstall` whenever it holds Omarchy Mobile. Everywhere else it stops and asks for `--bootloader-slots-match VERSION`, as before.
- **Qualcomm A/B phones (Pixel 4 family) keep the slot flags in GPT attributes,** so slot B can only be marked bootable by writing the partition table. That write is a narrow, named exception, never automatic: by hand, once per install of slot B's boot image, and only for a device whose entry in [CONTRIBUTING](CONTRIBUTING.md) §3.1 names the LUN, the four sectors (LBAs 1, 2, last-1 and last), the attribute bit and the CRCs it rewrites. That device's plan must also record the slot flags before and after, the rollback for a corrupted GPT, and the way back: stock restored on slot A first, or the owner's explicit acceptance of buttons-only recovery. The storage guard can't block this write, so it never runs from a service or at boot.
- **Linux never writes the modem's NV partitions** (`efs`, `efs_backup`, `modem_userdata`, `persist`, `modem_a/b`). The modem's own NV writes persist only in its per-phone overlay on userdata (`/var/lib/omamobile/modem-nv-overlay`, `omamobile-modem` 0.1.15+, off until `/etc/omamobile/modem-nv-overlay-enable` exists), only for the files on the overlay's allow-list (`efs/nv_normal.bin` and its checksum), never for identity or calibration files (`nv_protected.*`, all of `efs_backup`), and only while bound to the checksums in `/etc/omamobile/modem-nv.sha256`, so a new backup sets it aside. `omamobile-modem nv-overlay reset`, then a reboot, returns the modem to the backup alone. Don't add a file to the allow-list without the human's say-so, never write or edit the overlay by hand, and never commit it or copy it to another phone: it is that phone's NV. [MODEM-PLAN](device/cheetah/MODEM-PLAN.md) "NV overlay"
- **Never weaken the storage guard.** Don't `blockdev --setrw` a partition or recreate `/dev/sda`. Don't mount Android partitions read-write, and don't add names to the `UFS_RW` allowlist without the human's say-so. The guard is what keeps a bad command from erasing the IMEI.
- **Never weaken the storage guard.** Don't `blockdev --setrw` a partition or recreate a LUN's whole-disk node (`/dev/sda`, or a boot LUN's `/dev/sdb`-`/dev/sdd`). Don't mount Android partitions read-write, and don't add names to the `UFS_RW` allowlist without the human's say-so. The guard is what keeps a bad command from erasing the IMEI.
- **Check backups before radio, PMIC, AoC or Trusty work.** Run the checksum check of `efs`, `efs_backup`, `modem_userdata`, `persist` and `modem_a/b` against the off-repo backup first ([MODEM-PLAN.md](device/cheetah/MODEM-PLAN.md) M0.1). If there's no backup, stop. Find each partition by `PARTNAME` in `/sys/class/block/*/uevent`: the Arch root has no `/dev/disk/by-partlabel`. **Take a fresh read-only backup after any stock Android boot** (a slot A fallback counts): stock's modem stack writes `efs`, `persist` and `modem_userdata`, so the old checksums stop matching and the next check can't tell a change of ours from stock's.
- **Never read or write PMU registers from userspace** (no `devmem`, no `debugfs/regmap/*pmu*/registers`). PMU writes from userspace are silently ignored, and one read of a PMU G3D register crashed the phone. Use the kernel's SMC-backed `exynos-pmu` regmap.
- **`devmem` is `devmem ADDR [VALUE]`.** A second argument is written, so `devmem ADDR 32` writes 0x20. This once clobbered live DSIM timing registers.
Expand Down
10 changes: 5 additions & 5 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,11 +84,11 @@ Phones with an entry:

UFS holds the per-device calibration. The initramfs ([`initramfs/init`](initramfs/init)) guards it before anything else runs:

- It sets every SCSI disk and partition read-only (`blockdev --setro`) as soon as it appears, and keeps a watcher running for the life of PID 1.
- The only exceptions are an allowlist of GPT partition names: the device's `BOOT_IMAGES` on slot B, and `userdata`.
- It deletes the whole-disk node of the main LUN (`/dev/sda`), so nothing can write across partitions. The boot LUNs stay read-only at the disk level.
- In Arch, [`10-omamobile-storage.rules`](packages/omamobile-device-cheetah/vendor/udev/rules.d/10-omamobile-storage.rules) keeps the whole-disk node unusable and hides the Android partitions from desktop tools.
- The one write outside the allowlist is the boot-success marker (`omamobile-boot-success`). It opens exactly `devinfo` for a single verified write of the slot flag bytes, then sets it read-only again.
- It sets every SCSI partition's own read-only flag (`blockdev --setro`) as soon as it appears, and keeps a watcher running for the life of PID 1.
- The only exceptions are an allowlist of GPT partition names on the main LUN (`sda`), and on a LUN the descriptor's `UFS_RW_LUNS` names: the device's `BOOT_IMAGES` on slot B, and `userdata`.
- It deletes the whole-disk node of every LUN (`/dev/sda`, and the boot LUNs' `/dev/sdb`, `/dev/sdc`, `/dev/sdd`), so nothing can write across partitions, and leaves the disks' own flags clear. The kernel counts a partition read-only when its own flag or its disk's is set (`bdev_read_only()`), so a disk flag would hide every partition on that LUN, and opening one would mean opening all of them through the whole-disk node ([#252](https://github.com/derekross/omarchy-mobile/issues/252)). Before handing over to Arch it stays in the initramfs if any whole-disk node is still there or any partition outside the allowlist is writable. With an NFS root nothing on the UFS is written: the allowlist isn't loaded, and `sda` keeps its node and is read-only at the disk level as well.
- In Arch, [`10-omamobile-storage.rules`](packages/omamobile-device-cheetah/vendor/udev/rules.d/10-omamobile-storage.rules) keeps the main LUN's whole-disk node unusable, should it ever come back (devtmpfs makes a node only when the kernel adds a device), and hides the Android partitions from desktop tools.
- The one write outside the allowlist is the boot-success marker (`omamobile-boot-success`). It clears `devinfo`'s own flag alone for a single verified write of the slot flag bytes, then sets it read-only again; no disk flag is touched (under an initramfs from before #252, which still sets the disk flag, it opens the disk too, as it always did).

**A new device gets this guard before its UFS driver is ever enabled.** Check the device's LUN layout and partition names first, because the allowlist works by name.

Expand Down
48 changes: 48 additions & 0 deletions bin/omamobile
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,10 @@ Usage: [DEVICE=<codename>] omamobile <command>
(--from-slot-a: a development phone that fell back to stock on slot A)
push Write the images into slot B from the running phone over SSH,
verify them, and reboot into them (no fastboot)
On a phone whose device package ships omamobile-boot-success,
both check that its marker knows the images' storage guard
(#252): push reads it over SSH, flash needs
OMAMOBILE_MARKER_CHECKED=1 after checking by hand
kernel-shell Open a shell in the build environment, in the kernel tree
USAGE
}
Expand Down Expand Up @@ -265,6 +269,28 @@ images_for_device() {
# Is <image>_b on the device's storage-guard allowlist?
slot_b_allowed() { [[ " $DEV_UFS_RW " == *" ${1}_b "* ]]; }

# The storage guard of #252 removes the boot LUNs' whole-disk nodes. A
# boot-success marker from before it opens /dev/sdd first, so under the new
# guard it never marks slot B: harmless while B is marked, but after the next
# flash (which unmarks B) every boot spends one of B's tries until ABL falls
# back to slot A. Development phones get the init from this checkout and the
# marker from the installed device package, so for a device whose package
# ships the marker, push and flash check that the two match. The new marker
# carries this exact line.
MARKER_TAG='# guard: partition flags (#252)'
ships_boot_marker() { [[ -f $ROOT/packages/$DEV_PACKAGE/bin/omamobile-boot-success ]]; }
# Does $KERNEL_OUT's initramfs carry the #252 guard? Yes when it can't be
# read (no file, no lz4), so a doubt never skips the check.
initramfs_new_guard() {
local f=$KERNEL_OUT/initramfs.cpio.lz4 n
[[ -f $f ]] && command -v lz4 >/dev/null || return 0
n=$(lz4 -dc "$f" 2>/dev/null | grep -ac 'ufs_is_disk') || true
[[ ${n:-0} != 0 ]] || ! lz4 -t "$f" >/dev/null 2>&1
}
marker_check_hint() {
echo "check on the phone: grep -cxF '$MARKER_TAG' /usr/bin/omamobile-boot-success (1: ready; anything else: tools/phone-install-package packages/$DEV_PACKAGE first)"
}

# Does the device have this boot image? gs101 phones have no init_boot or
# vendor_kernel_boot.
has_image() { [[ " $DEV_BOOT_IMAGES " == *" $1 "* ]]; }
Expand Down Expand Up @@ -1257,6 +1283,13 @@ cmd_flash() {
[[ $DEV_BOOT_METHOD != qcom-abl ]] ||
die "flash refuses BOOT_METHOD=qcom-abl (no in-tree day-2 update path yet; see device/$DEVICE/BRINGUP-M1.md)"
images_for_device "$img"
# flash unmarks slot B, so the phone's marker must be able to mark it under
# these images' guard (#252). Fastboot can't read the installed package, so
# refuse unless the owner says it was checked: a warning would scroll by, and
# a wrong marker shows only as a fallback to slot A three boots later.
if ships_boot_marker && initramfs_new_guard && [[ ${OMAMOBILE_MARKER_CHECKED:-} != 1 ]]; then
die "flash unmarks slot B, and only an omamobile-boot-success that knows these images' storage guard (#252) marks it again; $(marker_check_hint), then run again with OMAMOBILE_MARKER_CHECKED=1"
fi
in_fastboot || die "phone not in fastboot (try: omamobile fastboot)"
local serial cur
serial=$(fastboot_serial) || exit 1
Expand Down Expand Up @@ -1336,6 +1369,21 @@ cmd_push() {
booted=$("$ssh" 'cat /proc/sys/kernel/random/boot_id') || die "cannot read the phone's boot id"
# dropbear's login PATH omits /usr/local/bin, where the initramfs installs reboot-to
"$ssh" 'PATH=/usr/local/bin:$PATH command -v reboot-to >/dev/null' || die "phone has no reboot-to; refusing to write"
# The phone's marker must know the guard the new initramfs brings (#252)
if ships_boot_marker && initramfs_new_guard; then
if [[ ${OMAMOBILE_MARKER_CHECKED:-} == 1 ]]; then
say "OMAMOBILE_MARKER_CHECKED=1: not checking the phone's omamobile-boot-success"
else
local mk
mk=$("$ssh" "if [ -f /usr/bin/omamobile-boot-success ]; then grep -cxF '$MARKER_TAG' /usr/bin/omamobile-boot-success || true; else echo missing; fi") \
|| die "cannot read the phone's omamobile-boot-success; refusing to write"
case $mk in
1) ;;
missing) die "the phone has no /usr/bin/omamobile-boot-success (the initramfs shell, or $DEV_PACKAGE not installed), so push can't tell whether it can mark slot B under these images' storage guard (#252); $(marker_check_hint), then run again with OMAMOBILE_MARKER_CHECKED=1" ;;
*) die "the phone's omamobile-boot-success predates these images' storage guard (#252) and could never mark slot B after the next flash: install $DEV_PACKAGE from this checkout first (tools/phone-install-package packages/$DEV_PACKAGE), then push" ;;
esac
fi
fi
# A kernel whose modules aren't installed boots without its drivers (the GPU
# among them): install them first. A config change can keep the release
# name, so compare the tarball's checksum, not just the directory.
Expand Down
Loading