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
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
3 changes: 2 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion docs/DEVICES.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) |