Skip to content
Closed
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 @@ -10,7 +10,7 @@ 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 one exception is `omamobile-fp`'s own start at boot (fingerprint below): its storageproxyd runs by default. 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` or, on a phone whose `/etc/omamobile/boot-update.conf` says `AUTO_WRITE=yes` (only `tools/install-phone` writes it, for a release install, or a human by hand in an approved runbook), `linux-omamobile`'s pacman hook `omamobile-boot-update` ([RELEASES](docs/RELEASES.md) §5.3, §12 decisions 3 and 10): it writes only `<image>_b` for the descriptor's `BOOT_IMAGES`, each found by GPT name on the main LUN, on `UFS_RW` and left `ro` 0 by the storage guard, read back by sha256, and never reboots. A development phone has no such file, so `push` stays its only writer. 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.
- **Qualcomm A/B phones (Pixel 4 family, OnePlus 6) 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, only through `tools/mark-slot-b` (ask the human before `--write`), and only for a device whose entry in [CONTRIBUTING](CONTRIBUTING.md) §3.1 names the LUN, the four sectors (both headers and the entry sector holding slot B's boot partition in each copy), 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.
- **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.
Expand Down
3 changes: 2 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,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. Slot B's boot images are written by `bin/omamobile flash` (fastboot) and `bin/omamobile push` (over SSH), and on a release install also by `linux-omamobile`'s pacman hook, `omamobile-boot-update` ([RELEASES](docs/RELEASES.md) §5.3, §12 decisions 3 and 10). The hook writes only when `/etc/omamobile/boot-update.conf` says `AUTO_WRITE=yes`, which only `tools/install-phone` writes (or a human by hand, in an approved runbook such as KERNEL-UPDATE-PLAN); it writes only `<image>_b` for the descriptor's `BOOT_IMAGES`, each found by GPT name on the main LUN, on the storage guard's allowlist (`UFS_RW`) and left read-write (`ro` 0) by the guard, which it never changes; it reads every image back, and never reboots. A development phone has no such file, so `bin/omamobile push` stays its only writer.
- **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.
- **Qualcomm A/B phones (Pixel 4 family, OnePlus 6) 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 four sectors (the primary header, the primary entry sector holding slot B's boot partition, the backup entry sector holding it, and the backup header, as LBAs), 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, and only through `tools/mark-slot-b`, which reads the entry from the descriptor's `SLOT_B_MARK` and refuses a GPT that doesn't match it (dry run by default). Entries:
- **enchilada (OnePlus 6):** LUN `sde` (4096-byte sectors, last LBA 786431, 96 entries in three sectors per copy); partition `boot_b`, entry 38; LBAs 1 (primary header), 3 (primary entries 32-63), 786428 (backup entries 32-63) and 786431 (backup header); attribute bit 54 (successful), set and nothing else; CRCs rewritten: the entry-array CRC in both headers, then each header's own CRC. The whole-disk node stays removed by the init: the tool reads and writes through a private node under `/run` that it removes on exit. Plan, flags and rollback: [enchilada NOTES](device/enchilada/NOTES.md#2026-11-09-the-31-entry-for-boot_b); the way back is the owner's [written acceptance](https://github.com/derekross/omarchy-mobile/issues/432#issuecomment-6758389898) that slot A holds the rescue.
- **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, never flash a bootloader partition to fix it: from stock Android, sideload the full OTA for your build twice, so each slot gets the same build. If that doesn't make them match, stop and ask in an issue.
Expand Down
25 changes: 15 additions & 10 deletions bin/omamobile
Original file line number Diff line number Diff line change
Expand Up @@ -1203,11 +1203,10 @@ cmd_flash() {
cmd_push() {
local img="$KERNEL_OUT/images" ssh="$ROOT/tools/phone-ssh" p dev want got rel
load_device
# Same class of refusal as flash: boot_b is on sde here, and there is no
# in-tree day-2 rewrite path for qcom-abl yet. Refuse before any phone I/O
# (modules-push would otherwise rewrite the running root's modules).
[[ $DEV_BOOT_METHOD != android-v0 ]] ||
die "push refuses BOOT_METHOD=android-v0 (RAM-only: fastboot boot \$KERNEL_OUT/images/boot.img)"
# android-v0 (enchilada) pushes like android-v4: its one image, boot_b, is
# found on a UFS_RW_LUNS LUN below. qcom-abl has no in-tree day-2 rewrite
# path yet: refuse before any phone I/O (modules-push would otherwise
# rewrite the running root's modules).
[[ $DEV_BOOT_METHOD != qcom-abl ]] ||
die "push refuses BOOT_METHOD=qcom-abl (no in-tree day-2 update path yet; see device/$DEVICE/BRINGUP-M1.md)"
images_for_device "$img"
Expand Down Expand Up @@ -1246,16 +1245,22 @@ cmd_push() {
# AVB_FOOTERS image is padded to the descriptor's partition size, with its
# footer at the end, so that size must be the partition's exactly.
local -A devs=()
local sectors bytes avb e
local sectors bytes avb e sys globs="" l
# The LUNs the init guards: sda, plus the descriptor's UFS_RW_LUNS
# (load_device checked those are sdb..sdz)
for l in sda ${DEV_UFS_RW_LUNS:-}; do globs+=" /sys/block/$l/$l*"; done
for p in $DEV_BOOT_IMAGES; do
slot_b_allowed "$p" || die "${p}_b is not on device/$DEVICE's storage-guard allowlist; refusing"
[[ -f "$img/$p.img" ]] || die "missing $img/$p.img (run: omamobile images)"
# Find the partition by GPT name; the init guard leaves only these writable
dev=$("$ssh" "for s in /sys/block/sda/sda*; do grep -qx 'PARTNAME=${p}_b' \$s/uevent && echo /dev/\${s##*/}; done; true")
[[ -n "$dev" ]] || die "${p}_b not found on the phone"
[[ "$("$ssh" "cat /sys/block/sda/${dev#/dev/}/ro")" == 0 ]] || die "$dev (${p}_b) is read-only; refusing"
sys=$("$ssh" "for s in$globs; do grep -qx 'PARTNAME=${p}_b' \$s/uevent && echo \$s; done; true")
[[ -n "$sys" ]] || die "${p}_b not found on the phone (looked on:$globs)"
[[ $sys != *$'\n'* ]] || die "${p}_b is on more than one partition (${sys//$'\n'/, }); refusing"
[[ $sys =~ ^/sys/block/(sd[a-z])/(sd[a-z])[0-9]+$ && ${BASH_REMATCH[1]} == "${BASH_REMATCH[2]}" ]] || die "unexpected partition path for ${p}_b: $sys"
dev=/dev/${sys##*/}
[[ "$("$ssh" "cat $sys/ro")" == 0 ]] || die "$dev (${p}_b) is read-only; refusing"
# sysfs counts 512-byte sectors, whatever the device's block size
sectors=$("$ssh" "cat /sys/block/sda/${dev#/dev/}/size")
sectors=$("$ssh" "cat $sys/size")
[[ $sectors =~ ^[0-9]{1,15}$ ]] || die "cannot read the size of $dev (${p}_b)"
bytes=$((sectors * 512))
(($(stat -c %s "$img/$p.img") <= bytes)) || die "$p.img is larger than ${p}_b ($dev, $bytes bytes); refusing"
Expand Down
66 changes: 64 additions & 2 deletions device/enchilada/NOTES.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,8 +47,8 @@ until the slot-B install and its CONTRIBUTING.md §3.1 entry are agreed.
| bootloader firmware (`xbl`, `abl`, `tz`, `modem`, ...) | OxygenOS firmware, identical on `_a` and `_b` | never written by this port | - |

**Writes made by hand.** Every write below was typed by hand, outside
`tools/install-phone` and `bin/omamobile` (whose installer path refuses
`android-v0`), and none will be repeated:
`tools/install-phone` and `bin/omamobile` (whose installer path refused
`android-v0` then), and none will be repeated:

- `fastboot`: `flash boot_a` and `flash system_a` (the rescue),
`erase dtbo_b`, `flash userdata`, `flash boot_b` twice, and
Expand Down Expand Up @@ -101,6 +101,68 @@ tree and goes away if stock is restored.
20 s and panics, and `panic=10` reboots the phone. ABL then starts the
active slot, A, which is the rescue.

## 2026-11-09: the §3.1 entry for boot_b

The plan for putting this port on slot B for good, and the one GPT write
it needs ([CONTRIBUTING](../../CONTRIBUTING.md) §3.1, enchilada entry).
Nothing below has run on the phone yet except the read-only GPT copy.

**The way back.** Slot A holds the Arch rescue, not stock, and stays that
way: the owner's written acceptance of buttons-only recovery through the
rescue is on [#432](https://github.com/derekross/omarchy-mobile/issues/432#issuecomment-6758389898).

**The install**, each step on the owner's go:

1. `tools/install-phone --dry-run`, then the install, with
`--bootloader-slots-match unreported` (ABL reports no bootloader
version; every firmware partition is identical on `_a` and `_b` in the
2026-11-05 backup). It writes `boot_b` and `userdata`, with
`AUTO_WRITE=no`, then `set-active b`. Day-2 kernels come by
`bin/omamobile push`, which finds `boot_b` on `sde`.
2. From that first boot of slot B: `tools/mark-slot-b --device enchilada`
(dry run), compared with the expected values below, then `--write`.

**The GPT write.** `sde`'s GPT, read 2026-11-09 from the rescue
(`sfdisk --dump`, and the raw sectors of both copies):

- 4096-byte sectors, 786432 of them; 96 entries of 128 bytes, entries in
LBA 2-4 (primary) and 786427-786429 (backup), headers at 1 and 786431;
- `boot_b` is `sde39`, entry 38, at byte 768 of LBA 3 and of LBA 786428;
- before the install its attributes read `0x003a000000000000`: priority
2, not active, 7 tries, not successful, not unbootable;
- CRCs then: entries `0x0a9fe94a`, primary header `0xb62ccea8`, backup
header `0x619c2dc8`. `set-active b` rewrites all three, so the tool
checks the live ones rather than these.

`tools/mark-slot-b` refuses unless the phone booted slot B, the GPT's
two copies are valid and equal, `boot_b` is found once at entry 38 in LBA
3 and 786428, and it is active and not unbootable. It then sets bit 54
only, rewrites the entry-array CRC and both header CRCs, and changes no
byte outside LBA 1, 3, 786428 and 786431. It writes the primary pair
first and reads it back before the backup pair, so a valid copy exists
at every moment. A dry run of its check against the 2026-11-09 copy found
entry 38 and the CRCs above.

**Slot flags, before and after** (A and B: successful / unbootable /
retry-count, `current-slot`):

| Read | `current-slot` | A | B |
| --- | --- | --- | --- |
| before, 2026-11-07 (above) | a | no / no / 5 | no / no / 7 |
| after the install's `set-active b` | to be recorded | | |
| after `mark-slot-b --write` | to be recorded | | |

**Rollback for a corrupted GPT.** A copy of `sde`'s LBA 0-5 and
786426-786431 (both GPT copies whole) and its `sfdisk --dump` were taken
read-only on 2026-11-09 and are kept off the repository: they hold the
disk's GUIDs. Should both copies end up invalid, boot the rescue on slot A
by the buttons (it keeps the whole-disk nodes), write the two ranges back
with `dd` (4096-byte blocks, `seek` 0 and 786426), and compare `sfdisk
--dump` with the saved one. That restores the attributes as they were
before the install, so the install's `set-active b` follows it. If only
one copy is invalid, ABL and `sfdisk` use the other, and the tool refuses
to run until both agree.

## 2026-11-08: the LUN-aware guard, booted RAM-only

`fastboot boot` of an initramfs built from commit 2331a85 (the
Expand Down
27 changes: 16 additions & 11 deletions device/enchilada/device.conf
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,16 @@
# Guarded SDM845 descriptor for the OnePlus 6 (enchilada). Format rules:
# device/cheetah/device.conf. Notes and the state of each slot: NOTES.md.
#
# RAM-only bring-up: this ABL boots an Android boot image header v0 holding
# a gzip kernel with the DTB appended (no dtbo, no vendor_boot), booted with
# `fastboot boot`, so nothing is written. `omamobile images` packs that
# boot.img from the header fields below (tests/images-layout); fastboot,
# flash, push and the installer refuse BOOT_METHOD=android-v0 before
# touching a phone (tests/boot-method), and keep refusing it until the
# slot-B install and its CONTRIBUTING.md §3.1 entry are agreed.
# This ABL boots an Android boot image header v0 holding a gzip kernel with
# the DTB appended (no dtbo, no vendor_boot). `omamobile images` packs that
# boot.img from the header fields below (tests/images-layout). The slot-B
# install is tools/install-phone (boot_b and userdata, then set-active b);
# its CONTRIBUTING.md §3.1 entry names the one GPT write that marks boot_b
# successful, by hand, once per install.
#
# Storage: userdata is on sda, but boot_* sit on LUN sde, so the shared
# init's sda-only guard keeps boot_b read-only (the same split as dodge).
# Storage: userdata is on sda, but boot_* sit on LUN sde. UFS_RW_LUNS=sde
# has the init guard sde as it guards sda, leaving only boot_b writable
# there, and push looks for boot_b on sde too.
# Never flash xbl/abl/vbmeta/modem/persist from an image.
#
# FASTBOOT_PRODUCT=sdm845 is ABL's `getvar product`: the SoC's name, which
Expand All @@ -38,8 +38,13 @@ TAGS_OFFSET=0x00000100

BOOT_IMAGES=boot
UFS_RW="boot_b userdata"
UFS_RW_LUNS=sde
# CONTRIBUTING.md §3.1: boot_b is entry 38 of sde's 96, 4096-byte sectors,
# last LBA 786431; tools/mark-slot-b sets its bit 54 in these four sectors.
SLOT_B_MARK="sde boot_b 1 3 786428 786431"
OMAMOBILE_SLOT=b
# The first-light kernel builds the USB gadget as modules (USB_CONFIGFS=m)
INITRAMFS_MODULES="libcomposite u_ether usb_f_ncm u_serial usb_f_acm"
# omamobile.initramfs: stay in the initramfs; RAM-only, nothing is mounted rw
CMDLINE="console=tty0 panic=10 omamobile.initramfs omamobile.ufs-probe"
# The init hands off to the Arch root on userdata. A RAM-only `fastboot boot`
# for bring-up adds omamobile.initramfs (stay in the initramfs) by hand.
CMDLINE="console=tty0 panic=10"
Loading