From 8a725fa046e954e38c727c647cc3043d2eebf4ab Mon Sep 17 00:00:00 2001 From: Derek Ross Date: Mon, 26 Oct 2026 19:19:34 -0400 Subject: [PATCH 1/2] AGENTS, CONTRIBUTING: userdata through install-phone; Qualcomm slot flags as a named exception MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two decisions the Qualcomm ports (#17/#55-#59 flame, #52 coral, #25 alioth) were waiting on: - AGENTS.md said never to run an unsuffixed fastboot flash, but our own tools/install-phone already flashes userdata that way behind its guards. The rule now says so: userdata has no slots, and it is flashed only through install-phone. - On the Pixel 4 family the A/B slot flags live in GPT attributes, so marking slot B bootable is a partition-table write the storage guard can't block. It is allowed only as a narrow exception named per device in CONTRIBUTING §3.1 (LUN, sectors, bit, CRCs), done by hand once per boot-image install, with the flags recorded before and after, a rollback for a corrupted GPT and a way back. Never automatic. No device has an entry yet. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 3 ++- CONTRIBUTING.md | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2eb978816..33d407df8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,7 +9,8 @@ Omarchy Mobile runs native Omarchy (Arch Linux ARM, Hyprland, Omarchy's packages - **Ask the human before every reboot, flash, `push`, overlay boot or irreversible write.** That includes RPMB writes, a first `storageproxyd` run, `devinfo` and anything under `/dev/sd*`. The phone is real hardware with calibration data that can't be replaced, and a human has to be ready to recover it. - **The phone is shared with a human. Announce anything that affects the screen or the feel of the phone before you run it**: DPMS, display modes and refresh rate, brightness, `bl_power`, haptics, the torch, the shell restarting, rotation. Otherwise they think the phone is broken, or it buzzes in their hand. -- **Only slot B and `userdata` are ours.** Write only `boot_b`, `init_boot_b`, `vendor_boot_b`, `vendor_kernel_boot_b` and `dtbo_b`, and only through `bin/omamobile flash|push`. Never touch bootloader, radio, `devinfo`, `persist`, `efs*`, `modem*` or `vbmeta`, and never run an unsuffixed `fastboot flash`. Slot A's stock Android is the way back. +- **Only slot B and `userdata` are ours.** Write only `boot_b`, `init_boot_b`, `vendor_boot_b`, `vendor_kernel_boot_b` and `dtbo_b`, and only through `bin/omamobile flash|push`. Never touch bootloader, radio, `devinfo`, `persist`, `efs*`, `modem*` or `vbmeta`, and never run an unsuffixed `fastboot flash`, with one exception: `userdata`, and only through `tools/install-phone` (serial pinned, codename typed, allowlist, dry run first). Slot A's stock Android is the way back. +- **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. - **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. - **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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fd4e7de15..fd47f59a1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,7 +56,8 @@ Every rule here exists because breaking it either bricks a phone or loses data n - Pixels have A/B slots. **Omarchy Mobile only ever lives on slot B.** Slot A keeps the stock factory build, so the phone always has a known-good system to fall back to and a way back to `fastboot` (`adb reboot bootloader`). - **We flash only these partitions:** the device's boot images on slot B (its descriptor's `BOOT_IMAGES`: `boot_b`, `vendor_boot_b` and `dtbo_b`, plus `init_boot_b` and `vendor_kernel_boot_b` where the phone has them), and `userdata`, which holds the Arch root. -- **Never flash** `bootloader`, `abl`, `bl1`/`bl2`/`bl31`, `pbl`, `radio`/`modem`, `devinfo`, `persist`, `efs*`, `modem_userdata`, `vbmeta`, or anything without an explicit `_b` suffix. `fastboot flash boot …` without a suffix writes whichever slot is active. +- **Never flash** `bootloader`, `abl`, `bl1`/`bl2`/`bl31`, `pbl`, `radio`/`modem`, `devinfo`, `persist`, `efs*`, `modem_userdata`, `vbmeta`, or anything without an explicit `_b` suffix, except `userdata` (it has no slots) and only through `tools/install-phone`, which pins the phone's serial, asks you to type the codename, checks an allowlist and runs a dry run first. `fastboot flash boot …` without a suffix writes whichever slot is active. +- **Qualcomm A/B phones (Pixel 4 family) store the slot flags in the partition table** (GPT attributes), and flashing `boot_b` clears `slot-successful:b`. Marking slot B bootable means writing four GPT sectors on the boot LUN, which the storage guard can't block. It is allowed only as a narrow, per-device exception, written into this section before it is used: the device, the LUN, the sectors (LBAs 1, 2, last-1 and last), the attribute bit and the CRCs it rewrites. The device's plan records 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 written acceptance of buttons-only recovery). It runs by hand, once per install of slot B's boot image, never from a service or at boot. No device has an entry yet. - **Never relock the bootloader** (`fastboot flashing lock`) while any non-stock image is on the phone. - **Never flash a factory image older than the one installed.** Pixels enforce bootloader anti-rollback. - Before your first flash, check that both slots carry the same bootloader version (`fastboot getvar all`). If they don't, stop and ask in an issue. From fd07e3148fdf9503560a7ecc98ea5a42c9cc4cd3 Mon Sep 17 00:00:00 2001 From: Derek Ross Date: Mon, 26 Oct 2026 19:40:51 -0400 Subject: [PATCH 2/2] DEVICES: the PinePhone Pro's codename and starting point The Wanted row had "-" as its codename, which omamobile.org prints next to the SoC ("-, Rockchip RK3399S"). It takes mainline's board name, pinephone-pro, and names that device tree, already in our kernel, as the starting point (promised on #47). Co-Authored-By: Claude Opus 5.5 --- docs/DEVICES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/DEVICES.md b/docs/DEVICES.md index 5c66dda0a..9c9b28aa5 100644 --- a/docs/DEVICES.md +++ b/docs/DEVICES.md @@ -71,4 +71,4 @@ Devices we'd like to support, with the closest starting point. Open an issue to | Pixel 10 family | mustang (10 Pro XL) | laguna (Tensor G5) | 10 Pro XL (mustang): stock facts, contributors welcome ([#18](https://github.com/derekross/omarchy-mobile/issues/18)) | | Pixel 11 Pro, 11 Pro Fold | grizzly, yogi | malibu (Tensor G6) | stock facts, contributors welcome: 11 Pro ([#26](https://github.com/derekross/omarchy-mobile/issues/26)), 11 Pro Fold ([#40](https://github.com/derekross/omarchy-mobile/issues/40)) | | POCO F3 | alioth | SM8250 (Snapdragon 870) | the first non-Pixel port: a guarded installer and root image in review ([#25](https://github.com/derekross/omarchy-mobile/pull/25)) | -| PinePhone Pro | - | Rockchip RK3399S | No port in this tree yet; prior art: [Omarchy on the PinePhone Pro](https://github.com/FlorencioJP/omarchy-mobile-pinephone-pro) | +| PinePhone Pro | pinephone-pro | Rockchip RK3399S | No port in this tree yet; mainline's `rk3399-pinephone-pro.dts` is already in our kernel. Prior art: [Omarchy on the PinePhone Pro](https://github.com/FlorencioJP/omarchy-mobile-pinephone-pro) |