Skip to content

feat(flash): port flash mode 2 to the Rust initramfs - #29

Merged
JanZachmann merged 41 commits into
omnect:mainfrom
JanZachmann:feat/flash-mode-2
Oct 8, 2026
Merged

JanZachmann merged 41 commits into
omnect:mainfrom
JanZachmann:feat/flash-mode-2

Conversation

@JanZachmann

@JanZachmann JanZachmann commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Ports flash mode 2 (legacy init.d/87-flash_mode_2) to the Rust initramfs. On flash-mode=2, or when /etc/enforce_flash_mode exists, the init clears the selector, unmounts everything on the running disk, brings up eth0 with dhcpcd, starts dropbear, and asks the operator to push wic.bmap and then wic.xz over scp -O. It flashes the image with bmaptool, handles the EFI entry on GRUB machines and reboots. By default a verify pass writes the image to RAM first; the new feature flash-mode-2-direct flashes straight from the scp stream.

  • New modules net.rs, bmap.rs and scp.rs, plus a /proc/mounts sweep in unmount.rs that compares device numbers.
  • New build constants BOOT_START, BOOT_SIZE (the zeroed head of the disk, as legacy non_bmap_dd_handling) and OMNECT_USER_ID (owner of the FIFO), new features flash-mode-2 and flash-mode-2-direct.
  • Per-mode policy in mod.rs: mode 2 reboots and writes flash-mode-2.log unless it failed while writing the disk; mode 1 is unchanged. Right after the flash pass the kernel re-reads the partition table, before the EFI step and the log mount; a failed re-read fails the run and writes no log file.

Reason

Mode 2 is the flash mode used in the development cycle, and meta-omnect cannot drop the legacy scripts for it until the Rust init supports it.

Things that differ from legacy on purpose:

  • Legacy writes no log file for mode 2. A failure before the disk is written leaves the disk intact, so its log file is kept; a failure while the disk is written leaves no log file.
  • The uid/gid of the omnect user and the direct-flashing switch are known to the recipe, so they are build-time values. The init does not read /etc/passwd.
  • The link wait and the address wait after dhcpcd returns are bounded (60 s and 120 s). A link-local address from the dhcpcd IPv4LL fallback is accepted, as in legacy. The wait for the operator's wic.bmap stays unbounded, but it ends only when the file has its closing </bmap> tag. With direct flashing the head of the disk is zeroed before bmaptool reads the bmap, so a half-written bmap would leave the disk unbootable.
  • The detection order follows legacy: a set flash-mode=1 wins, the flag file comes next, then flash-mode=2. Mode 2, from the flag or flash-mode=2, wins over a factory-reset set at the same time: the reset does not run and an error is logged. Asking for both is an operator mistake, so there is no further handling. Mode 1 keeps the refusal.
  • When /etc/enforce_flash_mode exists but the boot env can't be read, the init still runs mode 2, as in legacy.

Companion change: omnect/meta-omnect#697 (recipe exports, features, packages).

The mode 2 plan was written before mode 1 was done and had drifted from
it and from the legacy script: a stale EFI call, a stub unmount task,
--nobmap on the final flash, missing mkdir steps and a vague trigger
order. Direct flashing becomes a cargo feature and the omnect uid a
build constant, since the recipe knows both.

Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
scp creates wic.bmap before it writes the content. With
flash-mode-2-direct the disk head is zeroed before bmaptool reads the
bmap, so a half-written bmap left an unbootable disk. The wait now ends
only when wic.bmap is a regular file that ends with the closing </bmap>
tag.

Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
RealCloneOps and RealScpOps each forwarded every EfiOps method to
RealEfiOps. Both now hold a RealEfiOps and hand it out from efi().

Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
Mode 2 writes its run log to the freshly flashed data partition and
reboots, so the comments and log messages no longer say "source" or
"power off" only. The zeroing comment now says what legacy observed on
GRUB and U-Boot. Comments that restated the code or pointed at the spec
are cut.

Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
- project-context: rawio.rs and unmount.rs are gated on flash-mode,
  efi.rs on grub.
- spec 3.3: the two detection rows with an unreadable factory-reset.
- spec 5.4: the initramfs root is ramfs or tmpfs, depending on root=,
  and what each does when the image does not fit.
- spec 2.8: the tool table lists the resolved path.
- plan: where the Mode2 log_file arm, kb_to_bytes and zero_range live,
  and the bmap wait; PR notes are removed.
- README: the flash box covers mode 2 and its reboot.

Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
- spec 3.3: the flag with an unreadable factory-reset selects mode 2
  only when flash-mode is not 1.
- README: pivot_root fails on the initial rootfs, whatever its type.
- net.rs: the address poll relies on dhcpcd returning.
- plan: keep the open-question status of the flag decision.

Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
Comment thread src/mode/mod.rs Resolved
CI waits for flash mode 2 by logging in over ssh and listing wic.xz. It
fails when the login works but the FIFO is not there yet, which the old
order allowed.

Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
…2 flash

Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>

@JoergZeidler JoergZeidler left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review with the review-branch skill at 14ac9c6. Labels on every inline comment: High = wrong behaviour or a failing gate on a supported combination; Medium = a real gap with a narrow trigger, or a missing test for a destructive step; Low = docs, comments, conventions, small cleanups; Decision = needs an answer, not a code change by itself. No Critical: nothing writes a disk wrongly on every run.

Blocks merge

  • scp.rs:275 / mod.rs:271: a failure after the flash pass (EFI step) writes the run log through the stale partition table, and no test covers a step after the flash pass.
  • mod.rs:25: clippy fails on --no-default-features --features core,uboot,gpt,flash-mode-2,test-utils (unused PathBuf), the U-Boot production shape.
  • The Decision comment on mode/mod.rs:184 needs an answer in the PR text.

Machine checks (worktree of the PR head, toolchain 1.93.0, -D warnings plus the two repo lints)

Check Result
cargo fmt -- --check ok
clippy grub,gpt / uboot,dos (default set) ok
clippy --no-default-features core,grub,{gpt,dos},flash-mode-2, core,grub,gpt,flash-mode-2-direct ok
clippy --no-default-features core,uboot,gpt,flash-mode-2, core,uboot,dos,flash-mode-2-direct fails, unused import PathBuf
clippy grub,gpt,flash-mode-1,flash-mode-2,factory-reset,release-image,resize-data, uboot,gpt,flash-mode-1,flash-mode-2-direct,factory-reset ok
clippy --target armv7-unknown-linux-gnueabihf core,uboot,gpt,flash-mode-1,flash-mode-2,factory-reset ok
cargo test grub,gpt / uboot,dos 299 / 286 passed
cargo test --no-default-features core,grub,gpt,flash-mode-2 / core,uboot,gpt,flash-mode-2 / core,uboot,dos,flash-mode-2-direct / core,grub,gpt,flash-mode-2-direct 298 / 283 / 283 / 297 passed
cargo test with mode 1 + 2 + factory-reset (grub,gpt,...,release-image,resize-data / uboot,gpt,...,flash-mode-2-direct) 497 / 462 passed
cargo audit no advisories
i686 test run from the README not run, target not installed

Spec and plan

  • The spec **Status:** line still says "In review (PR #27)"; PR 27 is merged.
  • Spec §9 does not list that the unmount sweep now fails the run on an umount error where legacy ignored it (umount ... 2>/dev/null).
  • Spec §5.4 step 6 and the bmap.rs tests name /dev/omnect/rootblk; the code flashes layout.device.base, the same device by another path. Say so once, or use the base path in the spec.
  • All eight plan tasks map to code; the seven confirmed decisions are what the code does. Checked against the legacy flash-mode-2 and common-sh: trigger order, mkfifo/chown, instruction order, export PATH, verify → zero → flash, EFI after the flash on the old table, reboot -f; dd ... K is 1024, matching rawio::KIB.
  • meta-omnect#697 checked: feature mapping, the three exports, OMNECT_USER_ID 15581 for both groupadd -g and useradd -u, FLASH_MODE_2_PACKAGES, inherit omnect_user.

Not verified

  • /sbin/ip as a busybox applet in the initramfs; why /tmp is created before dhcpcd.
  • Whether the kernel re-reads the table on its own after bmaptool closes the whole-disk device (no udev in the initramfs, so the explicit BLKRRPART is right either way).
  • Where the feature combinations run in CI; no CI config in the repo.

Signed-off-by: Joerg Zeidler 62105035+JoergZeidler@users.noreply.github.com

Comment thread src/mode/flash/scp.rs Resolved
Comment thread src/mode/flash/mod.rs Resolved
Comment thread src/mode/flash/mod.rs Resolved
Comment thread src/mode/flash/scp.rs Resolved
Comment thread src/mode/flash/mod.rs Resolved
Comment thread src/mode/flash/mod.rs Resolved
Comment thread src/mode/flash/unmount.rs Resolved
Comment thread src/mode/flash/rawio.rs Resolved
Comment thread src/partition/device.rs Resolved
Comment thread src/mode/flash/net.rs Resolved
Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
…pass

A failure in the EFI step came after the disk was rewritten, but the
run log was then mounted through the table from before the flash. The
re-read now happens before the EFI step, so every later mount uses the
new table, and a failed re-read writes no log.

Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
An image pushed under the bmap name was read into RAM once per poll.

Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
…lock device

Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
A failed verify pass left the partial image in RAM. OpenSSH 9 uses SFTP
by default, which cannot write into the FIFO and has no server on the
device.

Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
…lper

Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
…state the code

Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
Comment thread src/mode/flash/scp.rs Resolved

@JoergZeidler JoergZeidler left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Round 2 at ed05047, 12 commits on top of 14ac9c6, no force push.

Every code finding from round 1 is fixed and verified against the new code; the fixed threads are resolved. One finding is accepted as not changed (stderr of the child tools, see the thread). Still open: the two questions to @HarryWaschkeit and @mlilien (flag with an unusable boot env, failed BLKRRPART after a complete flash), with my recommendation in each thread, and the three threads that follow the first answer (mode/mod.rs:184, mode/mod.rs:181, plan line 39). One new Low on the spec status line.

Machine checks (worktree of ed05047, toolchain 1.93.0, -D warnings plus the two repo lints)

Check Result
cargo fmt -- --check ok
clippy, 11 combinations: grub,gpt / uboot,dos (default set); --no-default-features core,{grub,uboot},{gpt,dos},flash-mode-2, core,uboot,{gpt,dos},flash-mode-2-direct, core,grub,gpt,flash-mode-2-direct; grub,gpt,flash-mode-1,flash-mode-2,factory-reset,release-image,resize-data; uboot,gpt,flash-mode-1,flash-mode-2-direct,factory-reset ok, including the two U-Boot mode-2 combinations that failed in round 1
cargo test, the same 11 combinations 299 / 286 / 303 / 302 / 287 / 288 / 286 / 287 / 302 / 502 / 466 passed, 0 failed
clippy --target armv7-unknown-linux-gnueabihf core,uboot,gpt,flash-mode-1,flash-mode-2,factory-reset ok
cargo audit no advisories
i686 test run not run here

Nothing blocks on the code side. Merge waits on the two answers and the plan, spec §3.3 and PR text aligned with them.

Signed-off-by: Joerg Zeidler 62105035+JoergZeidler@users.noreply.github.com

Comment thread src/mode/mod.rs Resolved
Comment thread src/mode/flash/scp.rs Resolved
Comment thread src/mode/flash/mod.rs Resolved
Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
@JanZachmann
JanZachmann requested a review from mlilien October 5, 2026 12:53
Comment thread src/config/mod.rs Resolved
Comment thread src/config/mod.rs Resolved
Comment thread src/mode/flash/bmap.rs Resolved
Comment thread src/mode/flash/config.rs Resolved
Comment thread src/mode/mod.rs Resolved
Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
Mode 2 overwrites the whole disk, so it includes the reset. Detection
no longer reads factory-reset for mode 2, and the mode clears it
together with flash-mode. Mode 1 keeps the refusal.

Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
…ring it

Asking for both is an operator mistake. Mode 2 still wins, but it no
longer clears factory-reset; detection logs an error that the reset
does not run.

Signed-off-by: Jan Zachmann <50990105+JanZachmann@users.noreply.github.com>
@JanZachmann
JanZachmann merged commit d28f57d into omnect:main Oct 8, 2026
@JanZachmann
JanZachmann deleted the feat/flash-mode-2 branch October 23, 2026 06:56
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