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
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@ Bring-up steps hang phones. Plan for it before you start:
2. Unplug and replug the cable once.
3. Force a restart: hold Power for about 30 s until the phone is off, then press Power. On the Pixel 8 Pro, hold Power + Volume Up for 15-30 s; Power alone does nothing under our kernel ([BRINGUP-M1](device/husky/BRINGUP-M1.md) test 23).
4. Reach fastboot by hand: with the phone off, hold Volume Down, add Power, and keep both held about 20 s until "Fastboot Mode" appears. Letting go early lands on the unlocked-bootloader warning, which carries on booting slot B.
5. From fastboot, flash known-good images to slot B, or `fastboot --set-active=a` to boot stock Android.
5. From fastboot, flash known-good images to slot B, or `fastboot --set-active=a` to boot stock Android. `bin/omamobile flash` refuses a phone whose `current-slot` is `a`, since a release installed on slot A looks the same from fastboot; for a development phone that fell back to stock on slot A, run `bin/omamobile flash --from-slot-a` (it warns, then writes slot B and makes it active).
- **Slot fallback:** a slot B that hasn't been marked successful falls back to stock slot A after the bootloader's retries run out. Once `omamobile-boot-success` has marked slot B, don't rely on that fallback: use fastboot. Keep a known-good image set (we keep one in `~/omamobile-kernel/known-good`).

### 3.5 Never touch PMU registers from userspace; mind `devmem`
Expand Down
51 changes: 48 additions & 3 deletions bin/omamobile
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,7 @@ Usage: [DEVICE=<codename>] omamobile <command>
fastboot Get the phone into fastboot without buttons (adb, reboot-to,
or crash until ABL falls back to stock Android on slot A)
flash Flash the experiment images to slot B and boot them
(--from-slot-a: a development phone that fell back to stock on slot A)
push Write the images into slot B from the running phone over SSH,
verify them, and reboot into them (no fastboot)
kernel-shell Open a shell in the build environment, in the kernel tree
Expand All @@ -102,6 +103,8 @@ die() { printf '\e[31merror:\e[0m %s\n' "$*" >&2; exit 1; }
# Every name a descriptor's UFS_RW may hold: slot B's boot images and
# userdata. Never persist, efs*, modem*, devinfo, vbmeta*, bootloader, radio
# or anything in slot A. initramfs/init's ufs_rw_load accepts the same set.
# The names are in slot form: the init maps each X_b to X of the slot the
# phone runs from, and leaves the other slot read-only (ACTIVE-SLOT-PLAN §4).
UFS_RW_ALLOWED="boot_b init_boot_b vendor_boot_b vendor_kernel_boot_b dtbo_b userdata"

# Load device/$DEVICE/device.conf into DEV_* variables. The descriptor is data,
Expand Down Expand Up @@ -587,6 +590,10 @@ initramfs_config() {
# The storage guard's allowlist. Without this file the init leaves every
# partition read-only.
printf '%s\n' "${rw[*]}" > "$etc/omamobile-ufs-rw"
# The list is in slot form (X_b); this marker says the init maps it to the
# slot the phone runs from (docs/ACTIVE-SLOT-PLAN.md §4). A format-2
# bundle is refused without it.
printf '%s\n' running > "$etc/omamobile-ufs-rw-slot"
if [[ -n ${DEV_UFS_RW_LUNS:-} ]]; then
printf '%s\n' "$DEV_UFS_RW_LUNS" > "$etc/omamobile-ufs-rw-luns"
fi
Expand Down Expand Up @@ -1219,7 +1226,13 @@ cmd_fastboot() {
}

cmd_flash() {
local img="$KERNEL_OUT/images" p
local img="$KERNEL_OUT/images" p from_a=0
case ${1:-} in
"") ;;
--from-slot-a) from_a=1 ;;
*) die "usage: omamobile flash [--from-slot-a]" ;;
esac
(($# <= 1)) || die "usage: omamobile flash [--from-slot-a]"
load_device
# Qualcomm ABL keeps slot flags in the GPT. A fastboot set_active can clear
# successful and refill retries; the bit-54 mark has no §3.1 entry yet.
Expand All @@ -1232,8 +1245,31 @@ cmd_flash() {
die "flash refuses BOOT_METHOD=qcom-abl (no in-tree day-2 update path yet; see device/$DEVICE/BRINGUP-M1.md)"
images_for_device "$img"
in_fastboot || die "phone not in fastboot (try: omamobile fastboot)"
local serial
local serial cur
serial=$(fastboot_serial) || exit 1
# Read-only: a release installed on the slot it ran from runs from slot A
# (docs/ACTIVE-SLOT-PLAN.md §2), and this writes slot B and makes it
# active, which is development only. Fastboot can't tell that release
# from stock Android on A, which a development phone falls back to (and
# `omamobile fastboot` crashes it into), so that case is named by hand
# with --from-slot-a.
cur=$(timeout 10 fastboot -s "$serial" getvar current-slot 2>&1 | sed -n 's/^current-slot: *_\{0,1\}\([ab]\)$/\1/p' | head -1)
if [[ $cur == a ]]; then
((from_a)) || die "this phone runs from slot A (a release from slot A, or stock Android); flash writes slot B and makes it active, development only. A development phone that fell back to stock on slot A: omamobile flash --from-slot-a"
printf '\e[1;31m' >&2
cat >&2 <<'WARN'
WARNING: --from-slot-a. This phone runs from slot A, and flash writes slot B
and makes it active. That is right only for a development phone that fell
back to stock Android on slot A. On a phone that runs a release from slot A
it switches the phone to slot B: the release's slot is left behind and both
systems share one userdata. Stop now (Ctrl-C) unless this is a development
phone. Going on in 10 seconds.
WARN
printf '\e[0m' >&2
sleep "${OMAMOBILE_FLASH_WARN_SECONDS:-10}"
elif ((from_a)); then
say "--from-slot-a given, but the phone reads current-slot ${cur:-unknown}: flashing as usual"
fi
# Every image and allowlist entry first: never start writing slot B and
# find out halfway that a later image is missing.
for p in $DEV_BOOT_IMAGES; do
Expand Down Expand Up @@ -1271,6 +1307,15 @@ cmd_push() {
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"
"$ssh" true || die "phone not reachable at 172.16.42.1"
# Read-only, before anything else (modules-push included): push writes
# slot B, so the phone must say it runs from B. A release installed on the
# slot it ran from runs from A (docs/ACTIVE-SLOT-PLAN.md §2); a boot that
# names no slot, or a failed read, is refused too.
local slots
slots=$("$ssh" "cat /proc/bootconfig /proc/cmdline 2>/dev/null | grep -oE 'androidboot[.]slot_suffix( = \"|=)_[ab]'; true") \
|| die "cannot read the phone's boot slot; refusing to write"
[[ $slots != *_a* ]] || die "this phone runs a release from slot A; push writes slot B, development only"
[[ $slots == *_b* ]] || die "the phone names no boot slot (androidboot.slot_suffix in /proc/bootconfig or /proc/cmdline); push writes slot B only to a phone running from it"
# Refuse before any write. A phone whose initramfs has no reboot-to would
# otherwise take the images, swallow the reboot, and report success while
# the old kernel is still running.
Expand Down Expand Up @@ -1371,7 +1416,7 @@ case "${1:-}" in
images) cmd_images ;;
kexec) cmd_kexec ;;
fastboot) cmd_fastboot ;;
flash) cmd_flash ;;
flash) shift; cmd_flash "$@" ;;
push) cmd_push ;;
kernel-shell) cmd_kernel_shell ;;
''|-h|--help) usage ;;
Expand Down
2 changes: 1 addition & 1 deletion device/cheetah/KERNEL-UPDATE-PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ No kernel branch: the kernel is the published release tag `kernel-2026.11.01`, b
- Before each write it saves slot B's five partitions, whole, and the running release's modules in `/var/lib/omamobile/boot/previous/` (about 220 MB on cheetah plus one module tree); `omamobile-boot-update rollback` writes them back.
- It never reboots, never touches slot A, `vbmeta`, `devinfo` or the bootloader, never changes the storage guard.

**Recovery when slot B doesn't boot.** `omamobile-boot-success` marks slot B successful at every good boot, so ABL does **not** fall back to slot A after a bad write: the phone stops in fastboot or keeps resetting, and `previous/` on `userdata` is out of reach. So the fallback lives on the laptop: step R2 copies the set slot B holds today into `~/omamobile-kernel/known-good/2026-11-02/images/` (with its `DEVICE` file) and checks the copy against the phone, and P3 also copies `previous/` off the phone before any reboot. Never flash from `~/omamobile-kernel/out-release`: other tools build into it (`tools/release build` writes the release kernel there). Then: Power held about 30 s, then Volume Down + Power about 20 s for fastboot, and on the laptop `KERNEL_OUT=~/omamobile-kernel/known-good/2026-11-02 bin/omamobile flash`. On the recovery screen of a stock boot choose neither option (AGENTS §4); a stock boot means a fresh read-only backup of `efs`, `persist` and `modem_userdata` afterwards.
**Recovery when slot B doesn't boot.** `omamobile-boot-success` marks slot B successful at every good boot, so ABL does **not** fall back to slot A after a bad write: the phone stops in fastboot or keeps resetting, and `previous/` on `userdata` is out of reach. So the fallback lives on the laptop: step R2 copies the set slot B holds today into `~/omamobile-kernel/known-good/2026-11-02/images/` (with its `DEVICE` file) and checks the copy against the phone, and P3 also copies `previous/` off the phone before any reboot. Never flash from `~/omamobile-kernel/out-release`: other tools build into it (`tools/release build` writes the release kernel there). Then: Power held about 30 s, then Volume Down + Power about 20 s for fastboot, and on the laptop `KERNEL_OUT=~/omamobile-kernel/known-good/2026-11-02 bin/omamobile flash`; if the phone fell back to stock on slot A (`fastboot getvar current-slot` reads `a`), `flash` refuses it and the same command takes `--from-slot-a`, which warns before it writes slot B and makes it active. On the recovery screen of a stock boot choose neither option (AGENTS §4); a stock boot means a fresh read-only backup of `efs`, `persist` and `modem_userdata` afterwards.

## 2. Why the running kernel can't be packaged as it is

Expand Down
5 changes: 4 additions & 1 deletion device/dodge/chainload/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,10 @@ our DTB without flashing `vendor_boot` is this chain:
`/omamobile/slot_suffix` (from `OMAMOBILE_SLOT` — this ABL puts the
property in neither bootconfig nor bootargs under `fastboot boot`;
stage 1 dumps both to kmsg and logs `source=packed`) (stage 1's own `/proc/cmdline` is
`CMDLINE_FORCE`d and has no ABL keys), and `kexec -c`
`CMDLINE_FORCE`d and has no ABL keys); it forwards `_b` only, since
stage 2's storage guard opens the slot it is told and this chain boots
slot B (any other value is logged and dropped, so stage 2's boot
partitions stay read-only); and `kexec -c`
into stage 2. Stage 1's kernel config has UFS disabled
(`SCSI_UFS_QCOM` / `SCSI_UFSHCD`), so it does not probe storage on
stock's DTB.
Expand Down
11 changes: 11 additions & 0 deletions device/dodge/chainload/init
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,17 @@ if [ -z "$SLOT_SUFFIX" ] && [ -f /omamobile/slot_suffix ]; then
SLOT_SUFFIX=$($B cat /omamobile/slot_suffix)
SLOT_SRC=packed
fi
# Stage 2's storage guard opens the boot images of the slot it is told
# (docs/ACTIVE-SLOT-PLAN.md §4), and this chain boots slot B only: forward
# _b alone. Anything else (slot A, a packed value, a stray string) is not
# forwarded, so stage 2 sees no suffix and keeps every boot partition
# read-only.
case $SLOT_SUFFIX in
""|_b) ;;
*)
echo "omamobile-chain: slot_suffix=$SLOT_SUFFIX source=$SLOT_SRC not forwarded (only _b is): stage 2 keeps every boot partition read-only" > /dev/kmsg 2>/dev/null || true
SLOT_SUFFIX= SLOT_SRC= ;;
esac
if [ -n "$SLOT_SUFFIX" ]; then
echo "omamobile-chain: slot_suffix=$SLOT_SUFFIX source=$SLOT_SRC" > /dev/kmsg 2>/dev/null || true
tok="androidboot.slot_suffix=$SLOT_SUFFIX"
Expand Down
14 changes: 13 additions & 1 deletion docs/ACTIVE-SLOT-PLAN.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,17 @@ Before: the radio-backup check passes; the home folder and settings are copied o

When every step passes, the maintainer adds the format-2 and accepted-slot lines to cheetah's descriptor and notes, and the next release is format 2.

### 6.1 The running-slot guard on a development phone (slot B), before any of the above

Step 2 of §7 changes what every phone boots (the init is in device-cheetah's boot files and in every `bin/omamobile initramfs`), so one development boot of it comes first. The 7 Pro on slot B, as today; every step is the maintainer's go; the device-cheetah version is set by the maintainer only after this boots.

| Step | What | Pass | Stop | Rollback | Risk |
| --- | --- | --- | --- | --- | --- |
| G0 | read only: `grep slot_suffix /proc/bootconfig`; for every `sd*` partition its `PARTNAME` and `ro` | `_b`; the five `_b` boot images and `userdata` `ro` 0, everything else 1 | another slot | none | none |
| G1 | `bin/omamobile initramfs`, `images`, then `systemctl stop omamobile-modem` and `bin/omamobile push` | SSH back on the new boot id | no SSH after about a minute (the safety net crashes back to fastboot or slot A) | `bin/omamobile flash` of the last known-good set (built by the current tool, footers included); after a fallback to stock on slot A (`current-slot` a), `bin/omamobile flash --from-slot-a`, which warns before writing | low: the guard is the only change |
| G2 | read only: `dmesg \| grep ufs-ro:`, G0's list again, `tools/phone-smoke` | "running from slot b", "allowlist: boot_b init_boot_b vendor_boot_b vendor_kernel_boot_b dtbo_b userdata"; the same `ro` values as G0; the boot and storage guard rows ok | any `_a` partition `ro` 0, or a `_b` boot image `ro` 1: write nothing, flash back | as G1 | none |
| G3 | a second `bin/omamobile push` of the same images | it writes and verifies through the guard, as before | a read-only refusal | as G1 (`flash`, or `flash --from-slot-a` after a fallback to slot A) | low |

## 7. The changes, in order

**First, changing no existing phone:**
Expand Down Expand Up @@ -126,4 +137,5 @@ When every step passes, the maintainer adds the format-2 and accepted-slot lines
6. **Version skew** fails closed both ways: old installers refuse format 2, old hooks refuse `SLOT=`; existing slot-B phones keep `SLOT=b` by default.
7. **The modem's slot** while `b` is accepted (§4).
8. **The reference phone ends with the release on A and the development system on B sharing one `userdata`.** How development continues is the maintainer's choice (likely `bin/omamobile flash` to B over the release root, or a separate development phone).
9. **Secure mode later** writes `vbmeta_<cur>` and the custom key with no stock fallback on a locked phone: SECURITY-PLAN's wording changes, not its design.
9. **A RAM boot (`fastboot boot`) with stock active on slot A now opens stock's `_a` boot images**: the bootloader names `_a`, and the running-slot guard maps the list to it. Before, such a boot opened slot B's. Nothing of ours writes there from a RAM boot (`push` requires `_b`, `omamobile-boot-update` requires its `SLOT`), but the guard no longer keeps stock's boot images read-only on it.
10. **Secure mode later** writes `vbmeta_<cur>` and the custom key with no stock fallback on a locked phone: SECURITY-PLAN's wording changes, not its design.
61 changes: 57 additions & 4 deletions initramfs/init
Original file line number Diff line number Diff line change
Expand Up @@ -46,25 +46,58 @@ fi
# Nothing in this initramfs runs mdev/udev, so no one else touches the disks.
ufs_ro_log() { echo "omamobile: ufs-ro: $*" > /dev/kmsg; }
# Storage guard. Everything on the UFS is read-only except an allowlist of
# partitions we own: slot B's boot images (in-place kernel updates) and
# userdata (the Arch root). The kernel only lets a partition be written if
# partitions we own: the running slot's boot images (in-place kernel
# updates) and userdata (the Arch root). The kernel only lets a partition be written if
# its whole disk is writable too, so the main disk (sda) stays writable but
# its whole-disk node is removed, so nothing can write across partitions by
# accident; a LUN the descriptor's UFS_RW_LUNS names is guarded the same way.
# The other LUNs (on Pixels sdb, sdc, sdd: bootloader images) are read-only
# at the disk level. Calibration partitions (efs, persist, modem_userdata...)
# and all of slot A stay read-only.
# and all of the other slot stay read-only.
# The allowlist is the descriptor's UFS_RW, which bin/omamobile initramfs
# checks and packs into /etc/omamobile-ufs-rw. It fails closed: a missing,
# empty or malformed file leaves every partition read-only, so Arch does not
# start and the initramfs shell stays up over SSH. Whatever the file says,
# only slot B's boot images and userdata can be named.
# The packed names are in slot form: X_b means "X of the slot this boot runs
# from" (docs/ACTIVE-SLOT-PLAN.md §4). The slot is the bootloader's
# androidboot.slot_suffix, from /proc/bootconfig, else /proc/cmdline. On
# slot B the list is what it says; on slot A each X_b becomes X_a and slot
# B stays read-only; with no readable suffix (none, or two that disagree)
# every boot partition stays read-only and userdata alone is writable.
# bin/omamobile initramfs packs /etc/omamobile-ufs-rw-slot ("running") to
# say this init maps the list so; any other content in it closes the guard.
UFS_RW=""
UFS_RW_LUNS=""
# Is $1 a disk that holds allowlisted partitions? sda always.
ufs_rw_disk() { case " sda $UFS_RW_LUNS " in *" $1 "*) true ;; *) false ;; esac; }
# The running slot's suffix: _a or _b, or nothing. Run it in a subshell
# ($(...)): it turns off globbing for the command line's words.
ufs_slot_add() { # one value: the first is kept, another one makes it unknown
case "$1" in _a|_b) ;; *) ufs_slot=bad; return 0 ;; esac
if [ -z "$ufs_slot" ]; then ufs_slot=$1
elif [ "$ufs_slot" != "$1" ]; then ufs_slot=bad; fi
}
# When bootconfig carries the key at all, it alone decides: an empty or
# unquoted value there is unknown, never a reason to read the command line.
ufs_slot_suffix() {
local w
ufs_slot=""
set -f
if [ -r /proc/bootconfig ] && [ -n "$(sed -n '/^androidboot\.slot_suffix *=/p' /proc/bootconfig)" ]; then
for w in $(sed -n 's/^androidboot\.slot_suffix *= *"\(.*\)" *$/\1/p' /proc/bootconfig); do
ufs_slot_add "$w"
done
[ -n "$ufs_slot" ] || ufs_slot=bad
elif [ -r /proc/cmdline ]; then
for w in $(cat /proc/cmdline); do
case "$w" in androidboot.slot_suffix=*) ufs_slot_add "${w#androidboot.slot_suffix=}" ;; esac
done
fi
case "$ufs_slot" in _a|_b) echo "$ufs_slot" ;; esac
}
ufs_rw_load() {
local list p
local list p slot mapped
if [ -s /etc/omamobile-nfsroot ]; then
ufs_ro_log "NFS root requested: every UFS partition read-only"
return 0
Expand Down Expand Up @@ -94,6 +127,26 @@ ufs_rw_load() {
return 0 ;;
esac
done
if [ -e /etc/omamobile-ufs-rw-slot ] && [ "$(cat /etc/omamobile-ufs-rw-slot)" != running ]; then
ufs_ro_log "malformed slot marker in /etc/omamobile-ufs-rw-slot: every partition read-only"
return 0
fi
# Slot form to the running slot: X_b is X of the slot this boot runs from
slot=$(ufs_slot_suffix)
mapped=""
for p in "$@"; do
case "$p" in
*_b) [ -z "$slot" ] || mapped="$mapped ${p%_b}$slot" ;;
*) mapped="$mapped $p" ;;
esac
done
if [ -n "$slot" ]; then
ufs_ro_log "running from slot ${slot#_}: its boot images are the allowlisted ones, the other slot stays read-only"
else
ufs_ro_log "no slot suffix in /proc/bootconfig or /proc/cmdline: every boot partition read-only, userdata writable"
fi
# shellcheck disable=SC2086 # split into names on purpose
set -- $mapped
UFS_RW="$*"
ufs_ro_log "allowlist: $UFS_RW"
# LUNs besides sda that hold allowlisted partitions (the descriptor's
Expand Down
2 changes: 1 addition & 1 deletion packages/omamobile-boot-update/PKGBUILD
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
pkgname=omamobile-boot-update
pkgver=$(cat "${startdir:-.}/version")
pkgrel=1
pkgdesc="Omarchy Mobile: rebuild a phone's slot-B boot images from linux-omamobile and write them, guarded and verified (pacman hook, opt-in)"
pkgdesc="Omarchy Mobile: rebuild a phone's boot images (slot B, or the slot boot-update.conf names) from linux-omamobile and write them, guarded and verified (pacman hook, opt-in)"
arch=(any)
url="https://github.com/derekross/omarchy-mobile"
license=(MIT Apache-2.0)
Expand Down
Loading