Skip to content

initramfs: load packed modules once, only where needed - #195

Merged
derekross merged 4 commits into
derekross:mainfrom
Gr-linkk:feat/module-load-once
Nov 10, 2026
Merged

derekross merged 4 commits into
derekross:mainfrom
Gr-linkk:feat/module-load-once

Conversation

@Gr-linkk

@Gr-linkk Gr-linkk commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

What and why

BusyBox insmod can retry initialization through init_module after finit_module fails. An initramfs module may already have touched hardware before returning an error.

The shared init's existing load_modules path now calls module-load-once once per packed module, preserving the board check, packed order, and failure reporting. The helper is built and included only when the device descriptor sets INITRAMFS_MODULES. Raven is the current caller; cheetah and oriole images do not acquire an unused helper. There is no fallback to insmod if the helper fails or is missing.

The helper preserves syscall errors and parameters and rejects empty/non-regular files without blocking on FIFOs. The previous general AGENTS rule and command-shell symlink are removed.

Review follow-up (2026-10-31)

This follows the requested INITRAMFS_MODULES integration. Current upstream main was merged without rewriting the submitted history. No packages, kernel configuration, storage policy, or automatic module list changed.

Checks

  • tools/pr-check upstream/main passes after the revision commit.
  • tests/all and tests/packages pass. Existing skips remain for unavailable Docker end-to-end, AOSP image tools/dtc/root-image fixtures, and package integrations such as the real Omarchy package.
  • tests/module-load-once intercepts the real C syscall: one attempt on success and failure, preserved parameters/errors, rejected invalid inputs.
  • tests/initramfs-steps executes the real extracted shell caller: matching/wrong board, absent list, ordered loads, helper failure and missing helper. Failures never retry through BusyBox. The new expectation fails on the old caller.
  • Actual initramfs builds: normal cheetah and oriole descriptors omit the helper. Synthetic module-bearing descriptors exercise Android-clang and host-clang paths; both archives contain a static ARM64 helper and preserve the fixture module order. Fixture images are not deployment images.
  • Independent read-only review found no implementation defect.

Hardware evidence and remaining check

The earlier Pixel 6 test used temporary files as UID 1000 on kernel 7.3.0-rc6-oriole-hsi1-late-dev0-g4bd35d34abb9-dirty. Its invalid fixture returned EPERM. That was unprivileged error-path coverage only; it did not exercise module initialization.

The revised initramfs has not been booted on Raven or another phone. Raven's existing module list is exynos-mailbox, acpm-protocol, sec-acpm, max77759, nvmem-max77759 and nvmem-reboot-mode. An affected-device boot should confirm those modules loaded, no module-load-once failure messages, and the normal phone-smoke result using the device's established guarded boot/rollback procedure. No Raven device is available in this setup. No phone operation was performed for this revision.

BusyBox can fall back from finit_module to init_module after an error.
A hardware probe may already have changed device state before failing,
so a second initialization defeats a staged bring-up experiment.

Build module-load-once with both initramfs toolchains and put it on
Dropbear's command path. It accepts an uncompressed module and optional
parameters, makes one finit_module call, and preserves the loading error.
Open nonblocking so a FIFO reaches the regular-file check without hanging.

The intercepted-syscall tests and tests/all pass. Both ARM64 initramfs
builds pass. QEMU confirms one attempt on ENOSYS; the same Alpine
BusyBox falls back to init_module. Pixel 6 usage, invalid-file and
unprivileged error paths pass, with exact cleanup and phone-smoke.
No valid module was loaded and the new initramfs images were not booted.

Assisted-by: Codex <noreply@openai.com>
@Gr-linkk Gr-linkk closed this Oct 30, 2026
@Gr-linkk Gr-linkk reopened this Oct 30, 2026
@derekross

Copy link
Copy Markdown
Owner

Thanks, the retry hazard is real and the tests are carefully made. As it stands, though, the tool has no caller but ships in every phone's boot image, the 7 Pro's included. The place where busybox would retry is load_modules in initramfs/init (raven's INITRAMFS_MODULES); kmod on the Arch root only falls back on ENOSYS. Could you either use it there, gated on INITRAMFS_MODULES, or bring it in with the bring-up stage that needs it? Please leave the AGENTS rule out; I'll add guidance once there's a user. (The phone run as UID 1000 got EPERM, so it never reached the kernel.)

The helper previously had no caller but shipped in every boot image.
Build it only when INITRAMFS_MODULES requests modules and call it from
load_modules, preserving the board gate, ordered loading and failure
reporting without a BusyBox retry. Drop the general diagnostic mandate.

Exercise the real shell caller with success, failure, missing-helper,
wrong-board and absent-list cases. Both compiler paths build static
ARM64 helpers with module fixtures; cheetah and oriole images omit it.
No revised initramfs has been booted on a phone.

Assisted-by: OpenAI GPT-6 Astra
@Gr-linkk Gr-linkk changed the title initramfs: load diagnostic modules with one syscall initramfs: load packed modules once, only where needed Oct 31, 2026
@derekross

Copy link
Copy Markdown
Owner

Thanks, this is the shape I hoped for, and the tests are good. It changes raven's boot only, so I'll ask the raven owner for one boot before merging: the six modules loaded, no loader errors, and phone-smoke.

@derekross

Copy link
Copy Markdown
Owner

Thanks, this is the shape now: gated on INITRAMFS_MODULES and called from load_modules, no AGENTS change, and I checked busybox's bb_init_module() myself (it does fall back from finit_module to init_module on any non-zero return). Both tests pass here. Still needed before I merge: the raven boot, which after #393 means three packed modules loaded (max77759, nvmem-max77759, nvmem-reboot-mode), no failed line, and a phone-smoke report. One suggestion: initramfs/init runs the helper with 2>/dev/null, so the errno it preserves never reaches the log; capturing it into say would make the first failure diagnosable. I'll write the squash message by hand.

Keep the loader error in the boot log so failed module initialization can be diagnosed without retrying it.
@derekross

Copy link
Copy Markdown
Owner

Thanks, @Gr-linkk. The error now reaches the boot log, and the test checks the message, so the first real failure will be diagnosable. That's all I wanted on the code side. The one thing left is the raven boot: three packed modules loaded, no "failed" line, and a phone-smoke report. I'll ask the raven owner for it, and merge with a hand-written message once it's in.

@derekross

Copy link
Copy Markdown
Owner

@robotosaith, could you give this one boot on your Pixel 6 Pro when you have a moment? It's the last thing #195 needs: an initramfs built from this branch (bin/omamobile initramfs then images from a checkout of it, pushed the usual way), and from that boot the dmesg lines showing the three packed modules loaded once each with no "failed" line, plus the tools/phone-smoke report. @Gr-linkk, thanks for your patience on this one.

@robotosaith

Copy link
Copy Markdown
Contributor

Ran this on raven today: the initramfs from 781687c (bin/omamobile initramfs from a checkout of this branch), booted from slot B with bin/omamobile push.

  • uname -r: 7.3.0-rc6-omamobile-push1-ge1e6adb69bbf
  • The kernel on this phone builds all six of raven's INITRAMFS_MODULES as modules, not the three you expected after bin/omamobile: skip built-in INITRAMFS_MODULES instead of failing #393, so the image packed six: exynos-mailbox acpm-protocol sec-acpm max77759 nvmem-max77759 nvmem-reboot-mode. All six read live in /sys/module/*/initstate. The kernel log has no "failed" line from the initramfs (it only writes one when the loader fails) and no File exists, init_module or finit_module errors, so each module loaded once. The reboot into this boot went through reboot-to, which needs nvmem-reboot-mode, and landed on slot B as expected.
  • How the image was built: this branch's images gave a DTB without raven's local overlays, which differs from what the phone runs. So I put the branch's initramfs into a vendor_boot that is otherwise byte-identical to the running one (same DTB, cmdline and header; only the ramdisk and its table entry changed). The kernel and dtbo match the running set too, so the boot tests only this PR's change.
  • Boot check: only Bluetooth fails. That's a separate problem: the chip has been silent for several boots before this push, the same as in raven's BLUETOOTH-PLAN B3. The cpif lines in the smoke report come from the modem's PCIe link, which is up at boot, and aren't related to this change.

phone-smoke: raven

Kernel 7.3.0-rc6-omamobile-push1-ge1e6adb69bbf, tools at 522a545f, 2026-11-10T10:30Z.

Check Result Detail
boot (required) ok kernel 7.3.0-rc6-omamobile-push1-ge1e6adb69bbf, slot b, up 154s
storage guard (required) ok 49 partitions; only userdata and slot B's boot images writable
root (required) ok ext4 on userdata, 97G free
kernel health (required) ok no oops or BUG; 0 WARN, 314 error lines in dmesg (0 known, 314 new)
new dmesg errors not ok cpif: mif_gpio_get_value: GET GPIO N is not valid x290; cpif: rx_demux: PCIE: ERR! N is not opened x8; cpif: pass_skb_to_demux: PCIE: N<N: ERR! N>recv_skb fail (N) x8
systemd units ok none failed
USB gadget (required) ok bound to 11110000.usb
display ok card2-DSI-1 connected, 1440x3120
GPU ok render node on panfrost
session (required) ok Hyprland and the Omarchy shell running
lock ok PAM file present, the shell can lock (passwordPam true, locked true)
touch ok s6sy761
buttons ok gpio-keys
Wi-Fi ok wlp1s0 on brcmfmac, link up
Bluetooth ok hci0, powered unknown
battery ok 98% Discharging, 30 °C
sound cards ok googleaocsndcar
sensors ok Accelerometer AmbientLight Proximity
cameras skip no libcamera tools
thermal ok hottest zone 43 °C

Packages: hyprland 0.57.0-3.1, libcamera 0.7.2-4.22, mesa 1:26.2.4-1.4, omacam 0.3.3-1, omamessages 0.2.1-1, omamobile-apps 0.2.2-1, omamobile-audio 0.5.15-1, omamobile-device-raven 0.1.35-1, omamobile-firstboot 0.1.3-1, omamobile-gnss 0.2.7-1, omamobile-keyring 20261026-1, omamobile-mirror 0.1.1-1, omamobile-mmd 0.1.4-1, omamobile-modem 0.1.17-1, omamobile-modem-sit 0.3.36-1, omamobile-omarchy 0.1.31-1, omamobile-owl-widgets 0.1.2-1, omamobile-sensors 0.2.1-1, omamobile-shell 0.2.94-1, omamobile-voice 0.1.0-1, omaphone 0.2.2-1, omarchy 4.0.6-1, omatel-agent 0.2.4-2, quickshell 0.3.2.r7.g2b4501a-1

@derekross

Copy link
Copy Markdown
Owner

Thank you, @robotosaith: that's exactly the boot this needed, and swapping only the ramdisk into the running vendor_boot was the right way to isolate it. Six modules live, no "failed" line in a log the init writes its failures to, and a clean required set in phone-smoke. I re-ran both tests and the new grep -q lint on this branch merged with today's main, and they pass.

@Gr-linkk, thanks for your patience and for the careful tests. I'm merging this with a hand-written message.

One thing changed while this waited: the OnePlus 6 descriptor landed on 11-07, and it also packs modules into the shared initramfs (its USB gadget: libcomposite u_ether usb_f_ncm u_serial usb_f_acm). So from this merge those load through the helper as well. When a load succeeds it's the same finit_module call busybox makes first, so I don't expect a difference, but @matthewjaybarr-png, on your next fastboot boot of a fresh image please check that the gadget comes up as before and that no "module-load-once … failed" line shows; if one does, the errno is in the line.

@derekross
derekross merged commit 6a9251f into derekross:main Nov 10, 2026
2 checks passed
@matthewjaybarr-png

Copy link
Copy Markdown
Contributor

Checked on the OnePlus 6. I did a fastboot boot (RAM-only) of a boot image built from main at 6a9251f, using the same 7.1.0-rc1-sdm845 kernel as the 11-08 boot.

  • The gadget came up as before. The laptop saw "OnePlus 6" about 10 s after fastboot boot, with ncm.usb0 and acm.GS0 bound to a600000.usb, and SSH over NCM works.
  • All five modules are loaded: libcomposite, u_ether, usb_f_ncm, u_serial and usb_f_acm.
  • dmesg | grep module-load-once prints nothing, so no load failed.

robertzas pushed a commit to robertzas/omarchy-mobile that referenced this pull request Nov 14, 2026
…od retry (derekross#195)

busybox insmod retries through init_module after a failed finit_module, and by then a module may already have touched hardware. The initramfs now loads each packed module with one finit_module call from a small helper, with no fallback, and the error reaches the boot log.

The helper is built and packed only where a descriptor sets INITRAMFS_MODULES (the Pixel 6 Pro and the OnePlus 6); nothing is packed and nothing changes for the other phones.

Tested on a Pixel 6 Pro on 2026-11-10 with this head: six modules live, no failure line. Not yet booted on a OnePlus 6.
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.

4 participants