Skip to content
Open
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 @@ -128,7 +128,7 @@ Each entry gives the gotcha, then the reason or the fix. Details are in the link
- **ABL leaves both cluster watchdogs running:** the phone resets at about 60 s of uptime unless `s3c2410_wdt` takes them over at probe.
- **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).
- **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). The reviewed way to mark B, once the maintainer has merged it and lifted this hold, is `omamobile-bootctl` from `omamobile-device-tegu`, run by hand from [BRINGUP-M1](device/tegu/BRINGUP-M1.md#6-slot-b-marked-successful-by-hand) §6 ([#252](https://github.com/derekross/omarchy-mobile/issues/252)); until then the hold above stands.
- **`reboot -f` and busybox `reboot` hang:** use `reboot-to <reason>` (`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.
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ Large trees live outside the repo: the Android-side sources, images and captures
## Ground rules

- We only ever flash the boot images and userdata. Never `bootloader`, `radio`, `devinfo`, `persist` or calibration partitions.
- **Licensing:** this repository is MIT ([LICENSE](LICENSE)) except where a file's SPDX header says otherwise. Kernel patches (and the board dtbo source) are GPL-2.0. The port of Google's Apache-2.0 boot-control code keeps that licence and Google's notice (`packages/omamobile-device-cheetah/src/omamobile-bootctl.c`). Every file we write carries an SPDX header.
- **Licensing:** this repository is MIT ([LICENSE](LICENSE)) except where a file's SPDX header says otherwise. Kernel patches (and the board dtbo source) are GPL-2.0. The ports of Google's Apache-2.0 boot-control code keep that licence and Google's notice (`packages/omamobile-device-cheetah/src/omamobile-bootctl.c`, and the husky and tegu packages' `bootctl/omamobile-bootctl.c`, each with `LICENSE.Apache-2.0` beside it). Every file we write carries an SPDX header.
- Google's proprietary firmware and binaries are never committed: our scripts extract them from the user's own factory image.
- No code from unlicensed sources. Google's GPL kernel, upstream Linux, postmarketOS and Mesa are fine.

Expand Down
112 changes: 112 additions & 0 deletions device/husky/BRINGUP-M1.md
Original file line number Diff line number Diff line change
Expand Up @@ -179,6 +179,118 @@ Findings:

The UFS boots that followed (U2, U3 and test K) are in husky's [UFS plan](UFS-PLAN.md).

## Slot B marked successful by hand

**Status (2026-11-07):** tool written, **never run on a phone**; it waits for
the maintainer's review of its pull request. Nothing here may run until the maintainer has merged the tool and the layout evidence below is on #252.

The decision on [#252](https://github.com/derekross/omarchy-mobile/issues/252):
slot B is marked successful by hand, attended, once per install of slot B's
images, and only after that image set has booted cleanly and passed
`tools/phone-smoke`. Never on the first boot of an untested image, and never
from a unit, a hook or the installer. Once B is marked, ABL no longer falls
back to slot A, so a broken image after that means fastboot by the buttons
(Power + Volume Up held 15-30 s to restart, then Power + Volume Down for fastboot, test 23). Any fastboot flash of slot B's images clears the mark again
(seen on the 9a, tegu NOTES 2026-10-31; expected on the 8 Pro, not yet seen); mark again only after the new set passes the smoke test.

The tool is `omamobile-bootctl` from `omamobile-device-husky`
(`packages/omamobile-device-husky/bootctl/omamobile-bootctl.c`, the same source as
the tegu package; this phone's values in `bootctl/bootctl-device.h`). It
refuses another board, a devinfo version other than 3.15 (the one recorded
for husky: [BATTERY-NOTES](BATTERY-NOTES.md) "The cure exists", and two owners' phones on #252), a boot from slot A, a slot B that isn't active or is
marked unbootable, and a storage guard that isn't holding (the main LUN's
whole-disk node usable, or any disk or partition outside `UFS_RW` writable).
It prints the devinfo version and the eight slot bytes 0x30-0x37, decoded,
and nothing else from the partition.

**Its read-write window.** The kernel can't write a partition of a read-only
disk: `bdev_read_only()` is the partition's own flag OR its disk's
(`include/linux/blkdev.h`), and the write path (`blkdev_write_iter()`), the
`BLKROGET` ioctl and sysfs `ro` all use it. So `devinfo` can't be made
writable while its boot LUN stays read-only, and the tool clears the LUN's
flag too, for as long as the one byte takes. **That exposes the whole LUN:**
while the disk's flag is clear, the whole-disk node is writable, and raw
writes through it reach every byte of the LUN, the other partitions on it
(`pinfo`, `blenv` and `mfg_data`) included; their own flags guard only their own nodes. Whether
that is acceptable is the maintainer's ruling on #252 and this tool waits
for it. The recommendation is to guard the boot LUNs as the main LUN is
guarded (whole-disk node removed, each partition's own flag set) in a
separate change tested on the 7 Pro; with that in place the window becomes
devinfo's flag alone.

The window, in order: refuse if devinfo, its LUN or a sibling is mounted or
held, or open for writing by any other process (checked again right before
the window, after the codename); the disk writable, and checked; each
sibling's and devinfo's own flag checked (the only moment a partition's own
flag can be read; any clear or unreadable one closes the window); devinfo
writable; devinfo read again and compared with what the checks saw; the
byte at 0x35 (slot B's flags) changed by OR 0x02 with `O_DSYNC` (the kernel
writes the 4 KiB block that holds it); the whole partition read back past the
page cache (`O_DIRECT`) and compared with the prediction (on a mismatch the
original is written back and read back, and the tool fails); devinfo
read-only and checked; the disk read-only and checked. ^C, SIGTERM and SIGHUP
are blocked. A relock child, started before the window, sets both flags back
the moment the tool exits or is killed, and from the moment the window
opens it also sets them back every 10 s for as long as the tool lives (a
stopped or hung tool), so the window can't stay open unwatched.

Each step: risk, command, expect / pass, stop, rollback. Record the results
here with the date and `uname -r`. Post only the version and the eight slot
bytes, never a dump.

1. **Preconditions** (none; read-only). The installed image set has booted
cleanly at least once and `tools/phone-smoke` passed on it (keep the
report). `pacman -Q omamobile-device-husky` shows the version with the tool,
built from the merged source. The layout evidence the maintainer asked for on #252 is
posted for this phone: the version, the eight slot bytes and `fastboot
getvar slot-successful:b`, `slot-unbootable:b` and `slot-retry-count:b`
read together, across one change ABL makes itself (a boot that spends a
try).
**Stop:** any of these missing. **Rollback:** none.
2. **Status** (none; read-only). `omamobile-bootctl status`.
**Expect:** `devinfo version 3.15 (the layout recorded for husky)`, `booted
from slot b`, `storage guard: holding`, slot b active, not successful, not
unbootable. **Stop:** any refusal, another version, slot a booted, the
guard not holding. **Rollback:** none.
3. **Dry run** (none; read-only: nothing is opened for writing).
`omamobile-bootctl mark-b-successful`. **Expect:** `planned: byte 0x35 XX
-> YY (slot b successful), nothing else`, where YY is XX OR 02, and the
write command with this boot's eight bytes. Post the output on #252 and
wait for the maintainer's go. **Stop:** any other plan, a refusal, no go.
**Rollback:** none.
4. **Read-only backup** (none; read-only). From the laptop,
`tools/nv-backup DIR` (devinfo is in the descriptor's `NV_BACKUP_EXTRA`),
then `tools/nv-backup --check DIR` right before step 5. Keep it off the
repository. **Expect:** every copy verified, and the check matches live
storage. **Stop:** a failed copy or a mismatch. **Rollback:** none.
5. **The write** (medium: one bit of `devinfo`, outside the allowlist). With a
kernel log stream to the laptop running and nobody about to reboot the
phone: `omamobile-bootctl mark-b-successful --write --codename husky
--expect "<the eight bytes from step 3>"`. Nothing changes on the screen.
**Expect:** exit 0, `before` and `after` lines that differ only in byte
0x35 by 0x02, then `slot b marked successful: written, read back, devinfo
and <its LUN> read-only again`. **Stop:** any other exit, and don't run it
again: exit 1 or 2 refused before anything was opened; 3, the write
failed or was put back and devinfo reads as before; 4, devinfo may differ
from the backup (don't reboot; post the output and wait); 5, a read-only
flag could not be restored (`systemctl reboot`: the initramfs sets it
again). **Rollback:** the mark is undone by flashing slot B's images
(`bin/omamobile flash` with a known-good set), which clears it; the
step 4 backup is for exit 4, and writing it back is the maintainer's call.
6. **Read back** (none; read-only). `omamobile-bootctl status` again, then
`tools/nv-backup --check DIR`. **Expect:** slot b successful, the guard
holding; the check differs only in `devinfo`, and a fresh read-only copy
of it differs from the backup in byte 0x35 alone (`cmp -l` prints one
line, offset 54). **Stop:** anything else. **Rollback:** as in step 5.
7. **ABL's view** (low: one trip to fastboot, which spends no try with B
marked). `reboot-to bootloader`, then, with this phone's serial pinned,
`fastboot -s <serial> getvar slot-successful:b`, `slot-unbootable:b` and
`slot-retry-count:b` (each with `-s <serial>`), then
`fastboot -s <serial> reboot`.
**Expect:** `yes`, `no`, and the phone boots slot B again. **Stop:** `no`
for successful: post it and don't repeat the write. **Rollback:** as in
step 5.

## Open questions

- ~~Does a bare DWC3 enumerate on the PHY and repeater state ABL leaves behind?~~ No: the PHY is off (test 17); with the eUSB2 PHY driven, the repeater as ABL leaves it works (test 18).
Expand Down
Loading