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: 3 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ Omarchy Mobile runs native Omarchy (Arch Linux ARM, Hyprland, Omarchy's packages
- **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.
- **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.
- **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 Expand Up @@ -98,6 +99,7 @@ tools/phone-ssh CMD -> run anything; stream files with ssh 'cat > f' < f
| `tools/phone-smoke` | Read-only smoke test of a running phone, with a report for the pull request: boot slot, storage guard, root, kernel health, USB, session, then display, GPU, touch, radios, battery, sound, sensors and cameras as evidence. `--here` on the phone, `--json` for a machine |
| `omamobile-update` (on the phone; `omamobile-omarchy`) | What `omarchy update` runs on the phone: Omarchy's own update with the phone's stand-ins (docs/RELEASES.md §5.4). `check --json` is read-only; an update changes the phone's packages and restarts the shell, so it is the human's call |
| `omamobile-boot-update status\|preflight\|write\|rollback` (on the phone; `omamobile-boot-update`) | Turns the installed `linux-omamobile` into slot B's images and writes them, guarded and verified ([RELEASES](docs/RELEASES.md) §5.3, §5.5); its pacman hook does nothing unless `/etc/omamobile/boot-update.conf` says `AUTO_WRITE=yes`, which development phones don't. `status`, `preflight` and `--dry-run` are read-only; `write` and `rollback` write slot B, so they are the human's call, like `push` |
| `omamobile-modem nv-overlay status\|diff\|capture\|reset [--all]` (on the phone; `omamobile-modem` 0.1.15+) | The modem's NV overlay (section 1): `status` and `diff` are read-only (`diff` lists what the modem changed since its start, names and sizes, and what would be kept); `capture` keeps the modem's allowed writes now (run it before a `reboot-to`, which skips the unit's stop); `reset` deletes the overlay, so the next boot runs from the backup alone. Turning it on (`/etc/omamobile/modem-nv-overlay-enable`) and resetting it are the human's call |
| `packages/linux-omamobile/stage KERNEL_OUT`, `tools/stage-boot-files` | Stage a kernel build for the kernel package, and a device's dtbo, overlays and release initramfs for its device package (gitignored `prebuilt/`, `boot-files/`); laptop only, no phone |
| `omamobile-omarchy-patches status\|verify\|apply` (on the phone) | The Omarchy patch series: what is applied, already upstream or failed; `apply` re-applies it all or nothing (the pacman hook does this after every Omarchy upgrade). Log: `/var/log/omamobile/omarchy-patches.log` |
| `tools/build-packages`, `tools/build-rootfs` | aarch64 packages (signed, `out/repo`) and the root image, built on the laptop in an Arch Linux ARM container (qemu-user); no phone |
Expand Down Expand Up @@ -192,7 +194,7 @@ Each entry gives the gotcha, then the reason or the fix. Details are in the link
- **UFS ran its error handler around modem power changes** (PA LINERESET indications, recovered without a reset). Stock's DT shows no shared rail, clock or pin. M2.5 narrowed it down: power-on and a running link are clean, but every modem power-off is followed by one recovered UFS error-handler pass (a PA LINERESET, no I/O errors or resets). Stock powers the modem off only at shutdown, so the modem stays on once it is up (M2.6 is open), and a reboot with the modem up costs one such pass. Keep modem tests attended, don't power-cycle the modem, and check `dmesg | grep ufshcd_err_handler` after each step. [MODEM-PLAN](device/cheetah/MODEM-PLAN.md) M2, M2.5, M2.6
- **Suspend with the modem on has never run on the 7 Pro, and is unqualified on the 9a**: its one try (2026-10-27) also had NFC polling, which alone resets the 9a in s2idle, so the modem's part is unknown. CPIF's PM paths are wake-armed in code, but M6 is design only and no SIM test has happened (M4.2). Keep modem tests on the charger, so upower's critical action doesn't suspend the phone mid-test. [MODEM-PLAN](device/cheetah/MODEM-PLAN.md) 6.3, [tegu MODEM-PLAN](device/tegu/MODEM-PLAN.md) "Suspend with the modem on"
- **Never `systemctl restart omamobile-modem` (or stop and start it) to recover a crashed modem.** An in-place restart left raven's CP in BOOTING, and a bring-up that never reaches ONLINE sets a latch that makes the next boot skip the modem. Reboot instead. If a boot skipped it, remove the latch (`rm /var/lib/omamobile/modem-bringup-started`) and `systemctl start omamobile-modem`; `/usr/lib/omamobile-vendor/omamobile-modem-start --retry` also clears it, but run by hand it brings the modem up outside the unit (a stray `rfsd` in your shell's session). From `omamobile-modem` 0.1.13 there is a second marker, `/var/lib/omamobile/modem-up`, written at ONLINE and removed by the unit's clean stop: a boot that hung or reset with the modem up leaves it, and the next boot refuses with "ended without a clean stop" until it is removed the same way (cheetah [MODEM-PLAN](device/cheetah/MODEM-PLAN.md) M4.6). On the 7 Pro the stack at boot is `systemctl enable omamobile-modem-boot.target`, opt-in; it also holds a sleep inhibitor until the reboot. [raven MODEM-PLAN](device/raven/MODEM-PLAN.md) D4. The same on the 9a: after the modem profile has stopped, starting it again in the same boot reset the palmtop silently, a watchdog reset with nothing in pstore (the one try was in the rfsd stage). [tegu MODEM-PLAN](device/tegu/MODEM-PLAN.md) G3. **From `omamobile-modem` 0.1.10, `omamobile-vendor-chroot modem check` refuses once the profile has started this boot** ("the modem profile already started this boot"), so it is no longer a post-install health check while the modem is up: it is read-only and safe to run, but a refusal means the profile ran, not that anything is wrong. After a reboot it says "preconditions met" again.
- **Linux never writes the modem's NV.** The modem chroot profile (cbd, rfsd) refuses to start unless the NV partitions read `ro=1` and none is mounted, works on checksum-verified RAM copies only, and loses what the modem writes at stop. Don't give the chroot a real block device.
- **Linux never writes the modem's NV partitions.** The modem chroot profile (cbd, rfsd) refuses to start unless the NV partitions read `ro=1` and none is mounted, and works on checksum-verified RAM copies only. What the modem writes is lost at stop, except its writes to `efs/nv_normal.bin` (expected to hold the carrier profile, network and IMS data; the runbook confirms it) when the NV overlay is on (section 1): those are captured every 30 minutes and at the unit's stop, after the CP is off, and laid over the verified copy at the next start. `reboot-to` (and `bin/omamobile push`) stops no unit, so run `omamobile-modem nv-overlay capture` first, or use `systemctl reboot`. Don't give the chroot a real block device. [MODEM-PLAN](device/cheetah/MODEM-PLAN.md) "NV overlay"

### USB

Expand Down
Loading