diff --git a/AGENTS.md b/AGENTS.md index 8174b5699..636a77ad3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -58,6 +58,7 @@ Omarchy Mobile runs native Omarchy (Arch Linux ARM, Hyprland, Omarchy's packages This leaves other people's staged and unstaged changes alone. - **Moving a feature from bring-up into a package:** bump the package `version`, enable nothing that isn't hang-safe, and delete the bring-up files from `/etc/modprobe.d` on the phone (`omamobile-*-bringup.conf`, and any hand-copied package file). A file in `/etc/modprobe.d` replaces the package's `/usr/lib/modprobe.d` file of the same name, so a stale `omamobile-aoc.conf` there hid the package's new blacklist. - **Kernel releases change with every push** (`7.3.0-rc6-omamobile-push1-NNNNN-g`). `bin/omamobile push` runs `modules-push` when the tarball's checksum differs. Without its modules a new kernel boots without its drivers, the GPU among them. `modules-push` replaces `/usr/lib/modules/` as a whole; on the 9a that once took a hand-installed panel driver with it, and the display stayed on the boot logo. It now refuses when the folder holds modules added or swapped by hand since the last push (it records what each push installed in `.omamobile-modules.sha256`), and `OMAMOBILE_MODULES_REPLACE=1` overrides that, wiping them. Pin a daily release whose folder carries hand-installed modules (`/usr/lib/modules/.omamobile-pinned`), and keep a copy before overriding (`tar -C /usr/lib/modules -cf … `). +- **Stop the modem before a `push` or a `reboot-to`.** `push` ends in `reboot-to`, a raw reboot syscall that stops no unit, so `omamobile-modem.service` never runs its clean stop and its `modem-up` marker stays. On the 7 Pro, where the modem starts at boot (device-cheetah 0.1.43+), the next boot then skips the modem once ("ended without a clean stop: a hang or a reset"), and a second such end before a clean stop holds it off until `omamobile-modem-start --retry`. This happened on 2026-11-08 after a `reboot-to bootloader` taken to charge a flat battery. So run `systemctl stop omamobile-modem` first, as part of the reboot the human said yes to; a reboot that needs no reason can be `systemctl reboot` instead, which stops it. The stop powers the CP off (one recovered UFS error-handler pass, as any reboot with the modem up costs) and, with the NV overlay on, captures its writes. For now it takes about 40 s and ends as "failed", with the CP's power-off logged as a crash; the marker is still removed ([#532](https://github.com/derekross/omarchy-mobile/issues/532)). This is not the restart the modem notes below forbid: nothing starts the modem again before the reboot. [#403](https://github.com/derekross/omarchy-mobile/pull/403), still open, would let the next boot start the modem after a `reboot-to`; the CP's ordered power-off and the NV capture would still come only from the unit's stop. [MODEM-PLAN](device/cheetah/MODEM-PLAN.md) M4.6b ## 3. How the tools fit together @@ -125,7 +126,7 @@ Each entry gives the gotcha, then the reason or the fix. Details are in the link - **ABL picks the base DTB by `soc_id`:** `bin/omamobile images` ships both silicon revisions. It also needs an empty `/ect` node and `/chosen/bootargs`, and applies a DPM overlay that needs label stubs (build with `-@`). - **Pixel 7 Pro: once slot B has booted with AVB footers, it needs them.** A stock install's `vbmeta_b` chains `boot` and `init_boot`. After one boot of #104's footer-carrying images, ABL refused footer-less ones (images built by any tool from before #104, or a saved older image set): it stopped in fastboot or used up B's tries and fell back to stock, whose recovery offered "Try again" or "Factory data reset". Build every image with the current `bin/omamobile`, keep rollback sets built the same way, and on that recovery screen choose neither: hold Volume Down + Power about 20 s for fastboot. A stock boot rewrites `efs`, `persist` and `modem_userdata`, so take a fresh read-only backup after one. [NOTES](device/cheetah/NOTES.md#2026-10-30-the-charger-reads-offline-at-full-and-slot-b-now-needs-its-avb-footers) - **Pixel 9a: a fallback to slot A costs the Linux root.** `fastboot --set-active=b` (which `bin/omamobile flash` runs) clears B's successful flag and gives B three ABL tries. A fastboot flash of slot B's images without `--set-active` clears the flag too: on 2026-10-31, `slot-successful:b` read `yes` before five suffixed flashes and `no` after, and the next boot started with `retry-count` 2 ([tegu NOTES](device/tegu/NOTES.md#2026-10-31-a-fastboot-flash-of-slot-b-cleared-its-successful-mark-and-b-was-marked-again)). Every boot uses one try, and the initramfs USB safety net (no USB host in about 65 s: panic) uses them fast. At zero ABL boots stock on slot A, and stock overwrote `userdata` on 10-28, and most likely on 10-26, before anyone could choose anything in recovery. So: `flash` only a known-good image set, and on the 9a ask the maintainer before any `flash` or fastboot write to slot B, because it unmarks B. Marking B successful is a `devinfo` write, and on the 9a it is on hold until the maintainer decides how it's done: don't mark B, and don't run `omamobile-bootctl` or anything that makes `devinfo` writable. With B marked, try new images with `push`, which doesn't call `--set-active` and leaves the mark alone; ABL then no longer falls back, so a broken pushed image means fastboot by the buttons, and the fastboot recovery leaves B unmarked: from then on every boot spends a try, so keep reboots few and ask the maintainer before marking B. With B unmarked, every boot spends one of the three tries: keep reboots few and don't test new images. [tegu NOTES](device/tegu/NOTES.md#2026-10-26-and-2026-10-28-slot-a-fallbacks-that-cost-userdata); the operation approved on 2026-10-22, now on hold: [NOTES](device/tegu/NOTES.md#approved-b-success-operation-after-layout-review-2026-10-22). -- **`reboot -f` and busybox `reboot` hang:** use `reboot-to ` (`LINUX_REBOOT_CMD_RESTART2`). ABL often ignores the `bootloader` reason anyway. +- **`reboot -f` and busybox `reboot` hang:** use `reboot-to ` (`LINUX_REBOOT_CMD_RESTART2`). ABL often ignores the `bootloader` reason anyway. It stops no unit, so stop the modem first (section 2). - **Reserved memory on gs201 is `#address-cells = <2>`, `#size-cells = <1>`,** so each `reg`/`alloc-ranges` entry is 12 bytes. A 16-byte value is silently ignored, and the pool lands anywhere. The display pool's `alignment` must be two cells too, or `of_reserved_mem` rejects it. `/proc/device-tree` shows the raw property, so it *looks* right. [WIFI-BATTERY-PLAN](device/cheetah/WIFI-BATTERY-PLAN.md) 9.x, [NOTES](device/cheetah/NOTES.md) - **Check every stock `reserved-memory` region against `/proc/iomem`:** five were plain System RAM in our kernel, and firmware writes into them at runtime. - **Don't make a driver depend on device-tree node order.** The AoC sound card numbered its PCMs in DAI link order, and the PCM number is the AoC entry point ID. Rewriting the overlay's node order changed nothing on the phone (`fdtoverlay` in our tree kept the source order), so the card driver now sorts its links by link id itself. [AOC-PLAN](device/cheetah/AOC-PLAN.md) C7d-5 @@ -193,8 +194,8 @@ Each entry gives the gotcha, then the reason or the fix. Details are in the link - **Volume Up is the one key without an internal pull** (`PUD` 0x0, as on stock), and the first freeze woke 3 s in from it with nobody touching it. It didn't recur in the 51 RTC cycles of S4 and S5c, and it isn't proven to be a false edge; if spurious wakes recur, check gpa8-5's power-down pull before blaming the wake path. - **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 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" +- **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 starts at boot by default since device-cheetah 0.1.43 ([MODEM-PLAN](device/cheetah/MODEM-PLAN.md) M4.6b); to keep it off from the next boot, `systemctl mask omamobile-modem-boot.target` (`unmask` turns it back on; `disable` doesn't remove device-cheetah's vendor wants link); 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 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`) skips that stop, so stop the modem first (section 2) or run `omamobile-modem nv-overlay capture`. Don't give the chroot a real block device. [MODEM-PLAN](device/cheetah/MODEM-PLAN.md) "NV overlay" ### USB diff --git a/device/cheetah/MODEM-PLAN.md b/device/cheetah/MODEM-PLAN.md index 2bd62cd81..3299dbfa2 100644 --- a/device/cheetah/MODEM-PLAN.md +++ b/device/cheetah/MODEM-PLAN.md @@ -2802,13 +2802,16 @@ tools/phone-ssh 'nmcli -f DEVICE,TYPE,STATE device | grep -c gsm; omamobile-sit # rollback: as B2 # B4 the second reboot: the clean stop clears the modem-up marker, and the next boot starts again -# (asks the human; risk: medium: one UFS pass) -tools/phone-ssh 'sync; (sleep 1; reboot-to omamobile) >/dev/null 2>&1 &' +# (asks the human; risk: medium: one UFS pass). Through systemd: `reboot-to` stops no unit, so the stop +# hook wouldn't run (AGENTS.md section 2) +tools/phone-ssh 'systemctl reboot' +# once the phone is back on USB (the modem's stop takes about 40 s, #532): tools/phone-ssh 'sleep 240; journalctl -b -1 -u omamobile-modem -o cat | grep -E "CP OFFLINE|stopped|removed|kept" | tail -3; systemctl is-active omamobile-modem omamobile-sitd omamobile-sit-data omamobile-mmd; omamobile-sit status | head -3; ls -l /var/lib/omamobile/modem-* 2>&1; dmesg | grep -c ufshcd_err_handler' -# pass: the previous boot's journal ends with "CP OFFLINE" and "modem stopped (success): ... modem-up -# removed"; active x4 and registered again; only this boot's modem-up; err_handler 0 on this boot +# pass: the previous boot's journal has "CP OFFLINE" and ends with "modem stopped (): ... modem-up +# removed" (the result is "timeout" until #532 is fixed; the removal is what counts); active x4 and +# registered again; only this boot's modem-up; err_handler 0 on this boot # stop: the modem unit refused with "ended without a clean stop" (the stop hook didn't run or ran on # another boot's marker: the -1 journal says which; the fix is in the package, not on the phone: # `systemctl disable omamobile-modem-boot.target`, remove the marker, and reboot); "never reached @@ -2955,7 +2958,7 @@ tools/phone-ssh 'sleep 240; systemctl list-units --no-pager "omamobile-modem*" o # keeps a marker that isn't this boot's (--stopped), so the next boot finds a stale one, refuses once, # moves it aside, and the boot after starts the modem again. No forced reset needed. tools/phone-ssh 'cat /var/lib/omamobile/modem-up; printf "%s boot %s\n" "$(date -Is)" 00000000-0000-0000-0000-000000000000 > /var/lib/omamobile/modem-up; sync; cat /var/lib/omamobile/modem-up' -tools/phone-ssh 'sync; (sleep 1; reboot-to omamobile) >/dev/null 2>&1 &' +tools/phone-ssh 'systemctl reboot' # through systemd, so the stop hook runs (B4); after it, once back on USB: tools/phone-ssh 'sleep 120; journalctl -b -1 -u omamobile-modem -o cat | tail -3; systemctl is-active omamobile-modem omamobile-sitd omamobile-sit-data omamobile-mmd; journalctl -b -u omamobile-modem -o cat; ls -l /var/lib/omamobile/modem-* 2>&1; cat /run/omamobile/modem-refused; systemd-inhibit --list --no-legend | grep -c omamobile-modem; dmesg | grep -c ufshcd_err_handler' @@ -2989,7 +2992,7 @@ tools/phone-ssh 'sleep 240; systemctl is-active omamobile-modem omamobile-sitd o # another boot's id again. The reboot's stop hook keeps the planted marker and the copy (not this boot's), # so the next boot finds both: the one automatic retry is used up, and it holds. tools/phone-ssh 'ls -l /var/lib/omamobile/modem-*; printf "%s boot %s\n" "$(date -Is)" 00000000-0000-0000-0000-000000000000 > /var/lib/omamobile/modem-up; sync' -tools/phone-ssh 'sync; (sleep 1; reboot-to omamobile) >/dev/null 2>&1 &' +tools/phone-ssh 'systemctl reboot' # through systemd, so the stop hook runs (B4); after it, once back on USB: tools/phone-ssh 'sleep 120; systemctl is-active omamobile-modem omamobile-sitd omamobile-sit-data omamobile-mmd; journalctl -b -u omamobile-modem -o cat | grep -E "clean stop|used up|moved"; ls -l /var/lib/omamobile/modem-* 2>&1; cat /run/omamobile/modem-refused; systemd-inhibit --list --no-legend | grep -c omamobile-modem; dmesg | grep -c ufshcd_err_handler' @@ -3001,9 +3004,9 @@ tools/phone-ssh 'sleep 120; systemctl is-active omamobile-modem omamobile-sitd o # -1 journal and the ls before the plant); the modem started (the planted marker was removed) # then: rm -f /var/lib/omamobile/modem-up*; reboot (asks the human); after 240 s: as B9's pass (active x4, # "CP ONLINE", this boot's modem-up, no refused copy, no modem-refused) -# then: one more clean reboot (asks the human; one UFS pass): the modem starts, this boot's modem-up, -# and ls /var/lib/omamobile/modem-up.refused-* finds nothing (the streak reset by --stopped at the -# reboot before: the copies are removed with this boot's marker) +# then: one more clean reboot, `systemctl reboot` (asks the human; one UFS pass): the modem starts, this +# boot's modem-up, and ls /var/lib/omamobile/modem-up.refused-* finds nothing (the streak reset by +# --stopped at the reboot before: the copies are removed with this boot's marker) # stop: a refused copy after the clean reboot (--stopped didn't remove them: journalctl -b -1 -u # omamobile-modem, "modem stopped"); refused on either boot # rollback: as B8