Skip to content

RELEASES: name the development boot policies stage-boot-files refuses - #908

Open
only21mil wants to merge 1 commit into
derekross:mainfrom
only21mil:build/releases-stage-boot-files-policies
Open

only21mil wants to merge 1 commit into
derekross:mainfrom
only21mil:build/releases-stage-boot-files-policies

Conversation

@only21mil

Copy link
Copy Markdown
Contributor

What and why

docs/RELEASES.md lists what tools/stage-boot-files refuses in a release initramfs: the builder's SSH keys, dropbear host keys and another device's allowlist. Since #831 the tool also refuses a development boot policy, and the list didn't say so. This is the docs pass invited in the merge note on #831. The note names §5.3; the list is in §5.5's tools/stage-boot-files entry (§5.3 doesn't mention the tool), so I changed it there.

The entry now states the rule the tool applies to the archive, with the names its messages use: any etc/omamobile-nfsroot (OMAMOBILE_NFSROOT) or etc/omamobile-root-mode (INITRAMFS_ROOT_MODE) is refused, and so is an etc/omamobile-usb-recovery (INITRAMFS_USB_RECOVERY) that is not one file saying yes. No other line in the file lists what the staging refuses. One line changes; no tool or test does. tests/stage-boot-files has covered these refusals since #831.

I had AI agents run the checks below on an x86_64 desktop. The block below shows the documentation sentence and the real staging tool on four archives at fe6fab42 and deb648ce.

Device and build

  • Phone: none: docs only
  • Kernel release (uname -r): no phone
  • Packages changed, with versions: none

Checks (no phone needed)

  • tools/pr-check origin/main passes (AI agent)
  • tests/all passes (AI agents ran every suite and all passed, one of them outside the sandbox; see below)
  • tests/packages passes (or the packages I touched: none, so not run)
  • Each changed package has its version bumped, and the new version is in the commit subject: no package changed
  • Commits have area prefixes and bodies that say why; any AI help is a Co-Authored-By: or Assisted-by: trailer, never a Signed-off-by:

On the phone

  • I ran this on my own phone, booted into this build: no: docs only
  • Runbook steps passed (plan, step, result): none, no plan step
  • What I did not test: CI or anything on a phone
  • Nothing in this change writes outside slot B and userdata, weakens the storage guard, or reads registers from userspace (AGENTS.md §1)
tools/phone-smoke report

Not applicable: a docs change that never runs on a phone (CONTRIBUTING.md §6.5).

On deb648ce, under bwrap --unshare-net with a docker stub that exits 1: tools/pr-check origin/main and tests/stage-boot-files passed, and tests/all passed through its last suite with tests/extract-vendor-firmware left out. That suite fails two "real ext4" cases in the sandbox's user namespace on the base too (debugfs gets EINVAL from chown); it names no URL and passed on its own outside the sandbox.

Setup: Ubuntu 26.04 on x86_64, bash 5.3.9, GNU cpio 2.15, lz4 1.10.0, no network; each commit's checkout; four initramfs archives built as tests/stage-boot-files builds them (cheetah's allowlist, the tree's init), with that test's stand-in for dtc and mkdtboimg.

Steps: print the §5.5 sentence → for each archive, run DEVICE=cheetah tools/stage-boot-files on it → print the output and exit status

Before, on fe6fab42, run before the change was written:

$ git rev-parse --short HEAD
fe6fab42

$ sed -n '/^### 5.5 /,/^## 6\./p' docs/RELEASES.md | grep -F -- '- **`tools/stage-boot-files`**' | sed 's/ It refuses a device with .*//'
- **`tools/stage-boot-files`** (`DEVICE=<codename> KERNEL_OUT=<build>`) prepares a device package's data in its gitignored `boot-files/`: the descriptor, `dtbo.img` (`bin/omamobile images`' commands), the compiled overlays and the release initramfs, which it refuses when it holds the builder's SSH keys, dropbear host keys or another device's allowlist.

## 1. a release initramfs
members: . etc etc/omamobile-ufs-rw init 
$ DEVICE=cheetah KERNEL_OUT=logs/fdoc-ev.1YX5ih/kout DTC=logs/fdoc-ev.1YX5ih/sbin/dt MKDTBOIMG=logs/fdoc-ev.1YX5ih/sbin/dt tools/stage-boot-files logs/fdoc-ev.1YX5ih/staged
staged cheetah's boot files in logs/fdoc-ev.1YX5ih/staged:
  SHA256SUMS
  SOURCES
  device.conf
  dtbo.img
  initramfs.cpio.lz4
  overlays/aoc-core-test.dtbo
  overlays/aoc-sound-test.dtbo
  overlays/audio-amps-test.dtbo
  overlays/camera-front.dtbo
  overlays/camera-main.dtbo
  overlays/camera-stream-link2.dtbo
  overlays/camera-tele.dtbo
  overlays/camera-uw-lens.dtbo
  overlays/fingerprint-sensor.dtbo
  overlays/gnss-pmic-test.dtbo
  overlays/gnss-test.dtbo
  overlays/modem-cpif-pktproc.dtbo
  overlays/modem-cpif-test.dtbo
  overlays/nfc-test.dtbo
  overlays/suspend-pmic-test.dtbo
exit status 0

## 2. an NFS root
members: . etc etc/omamobile-nfsroot etc/omamobile-ufs-rw init 
etc/omamobile-nfsroot: 192.0.2.1:/srv/nfs/sample
$ DEVICE=cheetah KERNEL_OUT=logs/fdoc-ev.1YX5ih/kout DTC=logs/fdoc-ev.1YX5ih/sbin/dt MKDTBOIMG=logs/fdoc-ev.1YX5ih/sbin/dt tools/stage-boot-files logs/fdoc-ev.1YX5ih/staged
stage-boot-files: logs/fdoc-ev.1YX5ih/kout/initramfs.cpio.lz4 carries etc/omamobile-nfsroot (OMAMOBILE_NFSROOT, bring-up only): build it with --release
exit status 1

## 3. a root mode
members: . etc etc/omamobile-root-mode etc/omamobile-ufs-rw init 
etc/omamobile-root-mode: persistent-development
$ DEVICE=cheetah KERNEL_OUT=logs/fdoc-ev.1YX5ih/kout DTC=logs/fdoc-ev.1YX5ih/sbin/dt MKDTBOIMG=logs/fdoc-ev.1YX5ih/sbin/dt tools/stage-boot-files logs/fdoc-ev.1YX5ih/staged
stage-boot-files: logs/fdoc-ev.1YX5ih/kout/initramfs.cpio.lz4 carries a root mode (INITRAMFS_ROOT_MODE, bring-up only): build it with --release
exit status 1

## 4. USB recovery off
members: . etc etc/omamobile-ufs-rw etc/omamobile-usb-recovery init 
etc/omamobile-usb-recovery: no
$ DEVICE=cheetah KERNEL_OUT=logs/fdoc-ev.1YX5ih/kout DTC=logs/fdoc-ev.1YX5ih/sbin/dt MKDTBOIMG=logs/fdoc-ev.1YX5ih/sbin/dt tools/stage-boot-files logs/fdoc-ev.1YX5ih/staged
stage-boot-files: logs/fdoc-ev.1YX5ih/kout/initramfs.cpio.lz4 carries an etc/omamobile-usb-recovery that is not one file saying yes (INITRAMFS_USB_RECOVERY, bring-up only): build it with --release
exit status 1

After, on deb648ce:

$ git rev-parse --short HEAD
deb648ce

$ sed -n '/^### 5.5 /,/^## 6\./p' docs/RELEASES.md | grep -F -- '- **`tools/stage-boot-files`**' | sed 's/ It refuses a device with .*//'
- **`tools/stage-boot-files`** (`DEVICE=<codename> KERNEL_OUT=<build>`) prepares a device package's data in its gitignored `boot-files/`: the descriptor, `dtbo.img` (`bin/omamobile images`' commands), the compiled overlays and the release initramfs, which it refuses when it holds the builder's SSH keys, dropbear host keys, another device's allowlist or a development boot policy: any `etc/omamobile-nfsroot` (`OMAMOBILE_NFSROOT`, which `bin/omamobile initramfs` reads from the environment) or `etc/omamobile-root-mode` (`INITRAMFS_ROOT_MODE`, §3), or an `etc/omamobile-usb-recovery` (`INITRAMFS_USB_RECOVERY`, §3) that is not one file saying `yes`.

## 1. a release initramfs
members: . etc etc/omamobile-ufs-rw init 
$ DEVICE=cheetah KERNEL_OUT=logs/fdoc-ev.FqfO0h/kout DTC=logs/fdoc-ev.FqfO0h/sbin/dt MKDTBOIMG=logs/fdoc-ev.FqfO0h/sbin/dt tools/stage-boot-files logs/fdoc-ev.FqfO0h/staged
staged cheetah's boot files in logs/fdoc-ev.FqfO0h/staged:
  SHA256SUMS
  SOURCES
  device.conf
  dtbo.img
  initramfs.cpio.lz4
  overlays/aoc-core-test.dtbo
  overlays/aoc-sound-test.dtbo
  overlays/audio-amps-test.dtbo
  overlays/camera-front.dtbo
  overlays/camera-main.dtbo
  overlays/camera-stream-link2.dtbo
  overlays/camera-tele.dtbo
  overlays/camera-uw-lens.dtbo
  overlays/fingerprint-sensor.dtbo
  overlays/gnss-pmic-test.dtbo
  overlays/gnss-test.dtbo
  overlays/modem-cpif-pktproc.dtbo
  overlays/modem-cpif-test.dtbo
  overlays/nfc-test.dtbo
  overlays/suspend-pmic-test.dtbo
exit status 0

## 2. an NFS root
members: . etc etc/omamobile-nfsroot etc/omamobile-ufs-rw init 
etc/omamobile-nfsroot: 192.0.2.1:/srv/nfs/sample
$ DEVICE=cheetah KERNEL_OUT=logs/fdoc-ev.FqfO0h/kout DTC=logs/fdoc-ev.FqfO0h/sbin/dt MKDTBOIMG=logs/fdoc-ev.FqfO0h/sbin/dt tools/stage-boot-files logs/fdoc-ev.FqfO0h/staged
stage-boot-files: logs/fdoc-ev.FqfO0h/kout/initramfs.cpio.lz4 carries etc/omamobile-nfsroot (OMAMOBILE_NFSROOT, bring-up only): build it with --release
exit status 1

## 3. a root mode
members: . etc etc/omamobile-root-mode etc/omamobile-ufs-rw init 
etc/omamobile-root-mode: persistent-development
$ DEVICE=cheetah KERNEL_OUT=logs/fdoc-ev.FqfO0h/kout DTC=logs/fdoc-ev.FqfO0h/sbin/dt MKDTBOIMG=logs/fdoc-ev.FqfO0h/sbin/dt tools/stage-boot-files logs/fdoc-ev.FqfO0h/staged
stage-boot-files: logs/fdoc-ev.FqfO0h/kout/initramfs.cpio.lz4 carries a root mode (INITRAMFS_ROOT_MODE, bring-up only): build it with --release
exit status 1

## 4. USB recovery off
members: . etc etc/omamobile-ufs-rw etc/omamobile-usb-recovery init 
etc/omamobile-usb-recovery: no
$ DEVICE=cheetah KERNEL_OUT=logs/fdoc-ev.FqfO0h/kout DTC=logs/fdoc-ev.FqfO0h/sbin/dt MKDTBOIMG=logs/fdoc-ev.FqfO0h/sbin/dt tools/stage-boot-files logs/fdoc-ev.FqfO0h/staged
stage-boot-files: logs/fdoc-ev.FqfO0h/kout/initramfs.cpio.lz4 carries an etc/omamobile-usb-recovery that is not one file saying yes (INITRAMFS_USB_RECOVERY, bring-up only): build it with --release
exit status 1

AI agents repeated the steps on the tree of main at 143f2ce7, whose only change from fe6fab42 is .github/workflows/checks.yml, and on its clean git merge-tree result with deb648ce (tree d144f063). The transcripts match the corresponding runs above apart from the reported HEAD SHA and the scratch directory name.

Links: the commit deb648ce; the refusals' test in tests/stage-boot-files; the invite on #831.

Not shown:

  • CI.
  • Phone smoke test (tools/phone-smoke). This change only edits documentation.
  • Package tests (tests/packages). No package changed.
  • A live Alpine-index fetch and full bin/omamobile initramfs --release build. This docs change covers staging, which the checks exercised with local archive fixtures.
  • A single unmodified tests/all run: tests/extract-vendor-firmware ran on its own outside the sandbox, as above.
  • Checks tests/all skipped on this machine: Docker end-to-end provisioning, two AOSP boot-image checks, SVE execution and the root-image smoke test.

Generated with Claude Opus 5.5 in T3 Code Nightly

The maintainer's note on derekross#831 asked for this in a later docs pass:
the docs list what tools/stage-boot-files refuses (SSH keys, host
keys, another device's allowlist) but not the development boot
policies it has refused since derekross#831. That list is in §5.5's
stage-boot-files bullet (§5.3 doesn't name the tool), so this adds
them there, with the archive rule the tool applies. No other line in
RELEASES.md lists what the staging refuses.

Docs only. Tested: tools/stage-boot-files on four lz4 cpio archives
built as tests/stage-boot-files builds them (cheetah's allowlist,
this tree's init), before and after: the release one stages, the
three with a policy file are refused, as the new sentence says.
tests/stage-boot-files (which covers these refusals since derekross#831) and
tools/pr-check origin/main pass in a sandbox without network.
tests/all passes in that sandbox with tests/extract-vendor-firmware
left out (its two real-ext4 cases fail in a user namespace, on the
base too), and that suite passes on its own outside the sandbox.
Not tested: nothing here runs on a phone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant