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 AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,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<sha>`). `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/<release>` as a whole, so modules installed there by hand (`updates/`, `extra/`, or a file swapped under `kernel/`) are gone after it runs; on the 9a that once took the panel driver with it, and the display stayed on the boot logo. Before pushing a release whose module folder carries hand-installed modules, keep a copy of the folder (`tar -C /usr/lib/modules -cf … <release>`).
- **Kernel releases change with every push** (`7.3.0-rc6-omamobile-push1-NNNNN-g<sha>`). `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/<release>` 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 … <release>`).

## 3. How the tools fit together

Expand Down
102 changes: 92 additions & 10 deletions bin/omamobile
Original file line number Diff line number Diff line change
Expand Up @@ -383,22 +383,87 @@ cmd_modules() {
}

cmd_modules_push() {
local rel tarball ssh="$ROOT/tools/phone-ssh" running
local rel tarball ssh="$ROOT/tools/phone-ssh" running checksum install command replace
rel=$(kernel_release)
[[ $rel =~ ^[0-9]+(\.[0-9]+)+[[:alnum:]_.+-]*$ ]] || die "invalid kernel release: $rel"
tarball="$KERNEL_OUT/modules-$rel.tar.zst"
[[ -f "$tarball" ]] || die "missing $tarball (run: omamobile modules)"
checksum=$(sha256sum < "$tarball" | cut -d' ' -f1)
replace=0
[[ ${OMAMOBILE_MODULES_REPLACE:-0} != 1 ]] || replace=1
"$ssh" true || die "phone not reachable at 172.16.42.1"
"$ssh" 'test -d /usr/lib/modules && command -v depmod >/dev/null' || die "phone is not in the Arch root (no /usr/lib/modules or depmod)"
running=$("$ssh" 'uname -r')
[[ "$running" == "$rel" ]] || echo " note: phone runs $running; installing $rel for the next boot"
say "Unpacking modules into /usr/lib/modules/$rel on the phone"
# Replace the whole tree so modules dropped from the config don't linger
"$ssh" "set -e; rm -rf /usr/lib/modules/.$rel.new; mkdir -p /usr/lib/modules/.$rel.new
zstd -dc | tar -C /usr/lib/modules/.$rel.new -xf -
rm -rf /usr/lib/modules/$rel; mv /usr/lib/modules/.$rel.new/$rel /usr/lib/modules/$rel
rmdir /usr/lib/modules/.$rel.new; depmod -a $rel
echo $(sha256sum < "$tarball" | cut -d' ' -f1) > /usr/lib/modules/$rel/.omamobile-tarball
echo $rel > /usr/lib/modules/.omamobile-next; sync" < "$tarball"
say "Staging modules for /usr/lib/modules/$rel on the phone"
# This script runs in bash on the Arch phone; stdin carries the archive.
# Compare module contents, not depmod's generated indexes or our markers.
install=$(cat <<'SH'
set -euo pipefail
rel=$1 checksum=$2 replace=$3
root=/usr/lib/modules
stage=$(mktemp -d "$root/.$rel.new.XXXXXX")
trap 'rm -rf -- "$stage"' EXIT
zstd -dc | tar -C "$stage" -xf -
incoming=$stage/$rel
installed=$root/$rel
[[ -d $incoming && ! -L $incoming ]] || { echo "archive has no module tree for $rel" >&2; exit 1; }
if [[ -L $installed || ( -e $installed && ! -d $installed ) ]]; then
echo "refusing non-directory module tree: $installed" >&2
exit 1
fi
# Every module's sha256, NUL-separated "sum<TAB>path" records relative to the tree.
module_sums() {
(cd "$1" && find . \( -type f -o -type l \) \( -name '*.ko' -o -name '*.ko.*' \) -print0 | sort -z |
while IFS= read -r -d '' f; do printf '%s\t%s\0' "$(sha256sum < "$f" | cut -d' ' -f1)" "${f#./}"; done)
}
if [[ -d $installed ]]; then
manifest=$installed/.omamobile-modules.sha256
conflicts=0
declare -A pushed=() incoming_sums=()
if [[ -f $manifest && ! -L $manifest ]]; then
# What the last push installed: a rebuilt module under the same release
# name is fine, a module added or swapped since by hand is not.
while IFS= read -r -d '' rec; do pushed[${rec#*$'\t'}]=${rec%%$'\t'*}; done < "$manifest"
while IFS= read -r -d '' rec; do
path=${rec#*$'\t'} sum=${rec%%$'\t'*}
if [[ -z ${pushed[$path]+x} ]]; then
printf 'module added by hand since the last push: %s\n' "$path" >&2; conflicts=1
elif [[ ${pushed[$path]} != "$sum" ]]; then
printf 'module changed by hand since the last push: %s\n' "$path" >&2; conflicts=1
fi
done < <(module_sums "$installed")
else
# A tree from before the manifest: every installed module must be in the
# archive unchanged (checksums, so no cmp: the release root has no diffutils).
while IFS= read -r -d '' rec; do incoming_sums[${rec#*$'\t'}]=${rec%%$'\t'*}; done < <(module_sums "$incoming")
while IFS= read -r -d '' rec; do
path=${rec#*$'\t'} sum=${rec%%$'\t'*}
if [[ ${incoming_sums[$path]:-} != "$sum" ]]; then
printf 'module absent or different in incoming archive: %s\n' "$path" >&2; conflicts=1
fi
done < <(module_sums "$installed")
fi
if (( conflicts )); then
if [[ $replace != 1 ]]; then
echo "refusing to replace $rel; installed tree untouched (OMAMOBILE_MODULES_REPLACE=1 permits replacement)" >&2
exit 1
fi
echo "OMAMOBILE_MODULES_REPLACE=1: replacing conflicting modules for $rel" >&2
fi
fi
# Only replace after extraction and every comparison succeeded.
rm -rf -- "$installed"
mv -- "$incoming" "$installed"
depmod -a "$rel"
module_sums "$installed" > "$installed/.omamobile-modules.sha256"
printf '%s\n' "$checksum" > "$installed/.omamobile-tarball"
printf '%s\n' "$rel" > "$root/.omamobile-next"
sync
SH
)
printf -v command '%q ' bash -c "$install" -- "$rel" "$checksum" "$replace"
"$ssh" "$command" < "$tarball"
"$ssh" "find /usr/lib/modules/$rel -name '*.ko*' | wc -l; ls /usr/lib/modules/$rel/modules.dep"
}

Expand Down Expand Up @@ -1080,8 +1145,25 @@ cmd_push() {
# among them): install them first. A config change can keep the release
# name, so compare the tarball's checksum, not just the directory.
rel=$(kernel_release)
[[ $rel =~ ^[0-9]+(\.[0-9]+)+[[:alnum:]_.+-]*$ ]] || die "invalid kernel release: $rel"
want=$(sha256sum < "$KERNEL_OUT/modules-$rel.tar.zst" | cut -d' ' -f1)
[[ "$("$ssh" "cat /usr/lib/modules/$rel/.omamobile-tarball 2>/dev/null")" == "$want" ]] || cmd_modules_push
local marker_status marker=/usr/lib/modules/$rel/.omamobile-tarball
# A missing marker needs an install; a failed read must never authorize one.
# Only stdout is the marker: an SSH warning on stderr isn't a mismatch.
local marker_err
marker_err=$(mktemp)
if got=$("$ssh" "if test -e '$marker' || test -L '$marker'; then cat -- '$marker'; else printf '%s\\n' '<missing>'; fi" 2>"$marker_err"); then
rm -f -- "$marker_err"
if [[ $got != "$want" ]]; then
say "Module marker for $rel: expected $want; read returned ${got:-<empty>}"
cmd_modules_push
fi
else
marker_status=$?
got="$got$(cat -- "$marker_err")"
rm -f -- "$marker_err"
die "cannot read module marker for $rel: expected $want; read exited $marker_status, returned ${got:-<empty>}"
fi
# Check every image before writing any. Each must fit its partition, and an
# 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.
Expand Down
6 changes: 5 additions & 1 deletion docs/RELEASES.md
Original file line number Diff line number Diff line change
Expand Up @@ -239,7 +239,11 @@ The same Alpine-based initramfs, with release differences:

**The phone's update UI** is `omamobile-shell`'s `omamobile.update` sheet: a toast when Omarchy has a release (tap to open) and Update > Omarchy in the menu open it; it shows what's new, the battery and the phone patches, asks for the PIN, shows progress with the output under Details, and ends on the result. The run is a systemd user unit, so it survives the shell restart at its end.

**Kernel module trees.** Omarchy enables `kernel-modules-hook`'s `linux-modules-cleanup.service`, which at every boot moves each `/usr/lib/modules/<release>` that isn't running and that no package owns into `.old`. A phone's kernels come from `bin/omamobile push`, so a boot between a push and the reboot into the new kernel took the next kernel's modules away (seen on the Pixel 7 on 2026-10-27). `omamobile-omarchy` 0.1.14 holds that unit off with a drop-in and runs `omamobile-modules-cleanup.timer` ten minutes after boot instead: it keeps the running release, the release `modules-push` last pushed (named in `/usr/lib/modules/.omamobile-next`), every tree pushed during this boot, every tree stamped before 2026 (a reset clock), every pacman-owned tree and the two newest others, and removes the rest (`/usr/lib/omamobile-omarchy/modules-cleanup --dry-run` shows what it would do). A removed tree comes back with the next `push`, which re-sends a tree whose `.omamobile-tarball` marker is missing. It never touches `.old`, which kernel-modules-hook's own tmpfiles rule empties.
**Kernel module trees.** Omarchy enables `kernel-modules-hook`'s `linux-modules-cleanup.service`, which at every boot moves each `/usr/lib/modules/<release>` that isn't running and that no package owns into `.old`. A phone's kernels come from `bin/omamobile push`, so a boot between a push and the reboot into the new kernel took the next kernel's modules away (seen on the Pixel 7 on 2026-10-27). `omamobile-omarchy` holds that unit off with a drop-in and runs `omamobile-modules-cleanup.timer` ten minutes after boot instead: it keeps the running release, the release `modules-push` last pushed (named in `/usr/lib/modules/.omamobile-next`), every tree pushed during this boot, every tree stamped before 2026 (a reset clock), every pacman-owned tree and the two newest others, and removes the rest (`/usr/lib/omamobile-omarchy/modules-cleanup --dry-run` shows what it would do). It never touches `.old`, which kernel-modules-hook's own tmpfiles rule empties.

Since `omamobile-omarchy` 0.1.32, `/usr/lib/modules/.omamobile-pinned` keeps additional releases indefinitely: list exact release names, one per line. Pins do not consume rollback slots and log as `keep <release>: pinned`. A missing file is empty; invalid lines and a symlinked pin file are ignored. Pin a daily kernel before experimenting with other kernels when its module tree contains hand-installed drivers. Re-sending the packaged archive cannot recover those drivers after cleanup deletes them.

`bin/omamobile modules-push` stages the incoming archive before replacing a release's tree. Each install records the sha256 of every module it installed (`.ko` or a compressed `.ko.*`, anywhere in the tree) in `.omamobile-modules.sha256`. The next push refuses, listing the paths and leaving the installed tree unchanged, only for a module missing from that manifest (added by hand) or not matching it (swapped by hand), so a rebuilt tree under the same release name installs. A tree from before the manifest is compared with the archive instead, by checksum: any installed module absent from it or different refuses, so the first push of rebuilt modules under an unchanged name onto such a tree refuses once. Generated depmod indexes and the markers are never compared. `OMAMOBILE_MODULES_REPLACE=1` explicitly permits discarding conflicting modules. `push` skips installation when the archive checksum matches `.omamobile-tarball`; a missing marker invokes the same guarded install, while a failed marker read stops the push and reports the release, expected checksum and read result.

### 5.5 What exists (2026-11-01)

Expand Down
24 changes: 22 additions & 2 deletions packages/omamobile-omarchy/lib/modules-cleanup
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@
# this instead, from omamobile-modules-cleanup.timer, well after boot.
#
# It keeps, in /usr/lib/modules:
# - releases listed one per line in /usr/lib/modules/.omamobile-pinned;
# - the running release (uname -r);
# - every tree that arrived during this boot: its marker's mtime, or the
# tree's mtime or ctime (a rename sets it), is after the boot time
Expand All @@ -30,8 +31,9 @@
# and removes the others with rm -rf. Only direct children named like a
# release ([0-9]*) are candidates; symlinks, dot-directories (.old, the
# .<release>.new of a push in progress) and plain files are never touched.
# A removed tree is recoverable: `bin/omamobile push` re-sends a tree whose
# marker is missing. When pacman can't answer, nothing is removed.
# A push can re-send packaged modules whose marker is missing, but cannot
# recover hand-installed modules: pin their release. When pacman can't
# answer, nothing is removed.
#
# modules-cleanup [--dry-run]
# Environment:
Expand Down Expand Up @@ -63,6 +65,16 @@ next=""
if [[ -f $root/.omamobile-next && ! -L $root/.omamobile-next ]]; then
read -r next < "$root/.omamobile-next" || true
fi
# Pins are exact release names, never paths, patterns or shell input.
# Ignore a symlink rather than following a file outside the module root.
pinned=()
if [[ -f $root/.omamobile-pinned && ! -L $root/.omamobile-pinned ]]; then
while IFS= read -r pin || [[ -n $pin ]]; do
if [[ $pin =~ ^[0-9]+(\.[0-9]+)+[[:alnum:]_.+-]*$ ]]; then
pinned+=("$pin")
fi
done < "$root/.omamobile-pinned"
fi
floor=1767225600 # 2026-01-01 UTC
btime=$(awk '$1 == "btime" { print $2; exit }' "${OMAMOBILE_PROC_STAT:-/proc/stat}")
[[ $btime =~ ^[0-9]+$ ]] || { log "no boot time in ${OMAMOBILE_PROC_STAT:-/proc/stat}; nothing removed"; exit 1; }
Expand Down Expand Up @@ -94,6 +106,14 @@ for tree in "$root"/[0-9]*; do
log "skip $name: not a directory"
continue
fi
is_pinned=0
for pin in "${pinned[@]}"; do
[[ $name != "$pin" ]] || { is_pinned=1; break; }
done
if (( is_pinned )); then
log "keep $name: pinned"
continue
fi
if [[ $name == "$running" ]]; then
log "keep $name: running"
continue
Expand Down
33 changes: 33 additions & 0 deletions packages/omamobile-omarchy/test/modules-cleanup.sh
Original file line number Diff line number Diff line change
Expand Up @@ -134,6 +134,39 @@ out=$(run) || fail "cleanup with a 1970 stamp"
grep -qxF 'modules-cleanup: keep 7.4.0-reset: its time is before 2026 (a reset clock), so its age is unknown' <<<"$out" || fail "logs the reset-clock tree"
pass "a tree stamped under a reset clock is kept, not ranked oldest"

# Pins do not consume rollback slots, even with three newer trees.
setup
tree 7.2.0-new3 2500 marker
printf '%s\n' '7.0.0-old2' > "$t/root/.omamobile-pinned"
out=$(run) || fail "cleanup with an older pinned tree"
[[ -d $t/root/7.0.0-old2 && ! -e $t/root/7.2.0-new3 ]] || fail "pin kept, third newer rollback pruned: $out"
grep -qxF 'modules-cleanup: keep 7.0.0-old2: pinned' <<<"$out" || fail "logs the pin"
[[ -d $t/root/7.2.0-new1 && -d $t/root/7.2.0-new2 ]] || fail "pin consumes no rollback slot"
pass "a pinned older tree survives three newer trees without consuming a rollback slot"

setup
# Include patterns, whitespace, traversal, shell text and an invalid tree name.
tree '7.0.0-garbage name' 6000 marker
printf '%s\n' '../7.1.0-old1' '7.*' ' 7.1.0-old1' '7.0.0-garbage name' '$(touch should-not-run)' '' > "$t/root/.omamobile-pinned"
# A valid last line without a newline is still a pin.
printf '%s' '7.0.0-old2' >> "$t/root/.omamobile-pinned"
out=$(run) || fail "cleanup with garbage pin lines"
[[ ! -e $t/root/7.1.0-old1 && ! -e "$t/root/7.0.0-garbage name" && -d $t/root/7.0.0-old2 ]] || fail "only the valid exact pin is honored: $out"
pass "garbage pin lines are ignored and a final line without a newline is read"

setup
printf '%s\n' 'garbage' '' > "$t/root/.omamobile-pinned"
out=$(run) || fail "cleanup with only garbage pin lines"
[[ ! -e $t/root/7.0.0-old2 ]] || fail "garbage-only file pins nothing"
pass "a file containing only garbage is treated as empty"

setup
printf '%s\n' '7.0.0-old2' > "$t/pins-outside"
ln -s "$t/pins-outside" "$t/root/.omamobile-pinned"
out=$(run) || fail "cleanup with a symlinked pin file"
[[ ! -e $t/root/7.0.0-old2 && -f $t/pins-outside ]] || fail "symlinked pin file is ignored"
pass "a symlinked pin file is skipped"

# An empty root and a missing one are fine
cp "$t/pacman.good" "$t/bin/pacman"
rm -rf "$t/root"; mkdir -p "$t/root"
Expand Down
2 changes: 1 addition & 1 deletion packages/omamobile-omarchy/version
Original file line number Diff line number Diff line change
@@ -1 +1 @@
0.1.31
0.1.32
2 changes: 1 addition & 1 deletion tests/all
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ sh -n device/flame/initramfs/init
sh -n device/flame/initramfs/build
bash -n tools/build-flame-probe
echo "ok - scripts parse"
for t in tests/pr-check tests/kernel-pr-check tests/phone-smoke tests/alarm-wake-test tests/install-phone tests/build-rootfs tests/phone-provision tests/nv-backup tests/initramfs-grow tests/images-layout tests/boot-update-parity tests/stage-boot-files tests/initramfs-reproducible tests/device-overlays tests/simplefb-trigger tests/initramfs-steps tests/storage-guard tests/usb-product tests/boot-method tests/make-bundle-keys tests/make-bundle tests/release-signing tests/flame-probe packages/omamobile-firstboot/test/all packages/omamobile-device-felix/test/all packages/omamobile-device-lynx/test/all packages/omamobile-device-panther/test/all tests/local-builds tests/phone-install-package tests/publish-kernel tests/fetch-toolchain tests/release-upload tests/extract-camera-data tests/release; do
for t in tests/pr-check tests/kernel-pr-check tests/phone-smoke tests/alarm-wake-test tests/install-phone tests/build-rootfs tests/phone-provision tests/nv-backup tests/initramfs-grow tests/images-layout tests/boot-update-parity tests/stage-boot-files tests/initramfs-reproducible tests/device-overlays tests/simplefb-trigger tests/initramfs-steps tests/storage-guard tests/usb-product tests/boot-method tests/modules-push tests/make-bundle-keys tests/make-bundle tests/release-signing tests/flame-probe packages/omamobile-firstboot/test/all packages/omamobile-device-felix/test/all packages/omamobile-device-lynx/test/all packages/omamobile-device-panther/test/all tests/local-builds tests/phone-install-package tests/publish-kernel tests/fetch-toolchain tests/release-upload tests/extract-camera-data tests/release; do
echo "# $t"
"$t"
done
Expand Down
Loading