Add optional boot confirmation and rollback for the disk boot path

[dgarske]

Summary

Adds optional boot confirmation and automatic rollback (DISK_BOOT_CONFIRM=1) for disk-based boot targets using a partition trailer state machine.

Key Changes

• Trailer Format (include/disk_trailer.h): Defines on-media format, magic bytes, and states (IMG_STATE_*) shared between loader and userspace tools.
• Loader State Machine (src/update_disk.c): Reads slot state, drops unconfirmed slots from selection, and marks staged slots as testing prior to handoff.
• Runtime Backing Store (hal/library_fs.c, hal/filesystem.c): Enables lib-fs to stage and confirm any slot by device path.
• Build Configuration (options.mk): Adds the DISK_BOOT_CONFIRM option for disk-boot targets.
• Tests & Docs: Adds host unit test (tools/unit-tests/unit-update-disk-confirm.c), CI job for cm4_sdcard, and documentation (docs/compile.md).

Design Constraints

• Disabled by default: Off unless explicitly enabled. Existing targets build byte-identically when disabled.
• State Behavior: Unconfirmed slots are dropped from election without modifying anti-rollback limits. Raw partitions only (DISK_FS excluded).
• Write Minimization: Steady-state boots and un-updated slots perform no writes.

Verification

• Hardware-validated on an i.MX 8QuadMax MEK booting a signed Linux FIT from SD, across three power cycles with both the loader and lib-fs from this branch:
  • lib-fs --dev <slot> stage wrote UPDATING; wolfBoot selected that slot, promoted it to TESTING and booted it.
  • Left unconfirmed, the next boot reported Slot A was not confirmed; skipping it, dropped its version from the election and booted the other slot.
  • The skip wrote nothing: the slot still read TESTING afterwards.
  • After lib-fs --dev <slot> success, the slot was selected, booted, and left untouched - a steady-state boot performs no writes.
• A blank partition tail reads as NEW rather than SUCCESS on real media, which is the case the trailer magic exists to catch.
• update-trigger is refused with --dev, leaving the 64 MB slot bit-identical, since it would otherwise write the UPDATE trailer at a compile-time offset into the middle of the slot.
• Host unit tests pass.

[Copilot]

🟡 Changes recommended

The new --dev disk trailer code in hal/library_fs.c uses fseek()/ftell() with long, which can mis-handle offsets/sizes on 32-bit hosts or large (>2GiB) devices/images.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds an optional “boot confirmation + automatic rollback” mechanism for disk-boot targets, using a small on-media trailer state machine shared between the bootloader and the userspace lib-fs tool.

Changes:

• Introduces a shared disk trailer format/state definitions (include/disk_trailer.h) and wires a slot state machine into the disk boot path (src/update_disk.c) when DISK_BOOT_CONFIRM=1.
• Extends lib-fs to operate on arbitrary backing stores via --dev <path>, including staging/confirming slot state in the device tail (hal/library_fs.c, hal/filesystem.c, include/hal.h).
• Adds a dedicated host unit test and CI coverage for the new disk confirmation path, plus documentation (tools/unit-tests/*, .github/workflows/test-configs.yml, docs/compile.md).

File summaries

File	Description
tools/unit-tests/unit-update-disk-confirm.c	New unit test suite covering disk slot state transitions and edge cases (overlap/min-size/unconfirmed).
tools/unit-tests/Makefile	Adds the new unit test target and build flags.
src/update_disk.c	Implements optional disk-slot state read/reap and arming (UPDATING→TESTING) before handoff.
options.mk	Adds DISK_BOOT_CONFIRM build option gating and validation.
include/hal.h	Declares hal_filesystem_set_target() for the filesystem HAL.
include/disk_trailer.h	Defines the on-media trailer layout and pinned state values shared by loader/tool.
hal/library_fs.c	Adds --dev support and disk-slot status/stage/success commands using the trailer tail format.
hal/filesystem.c	Allows repointing the filesystem HAL backing store at runtime.
docs/compile.md	Documents the disk confirmation lifecycle, staging/confirming workflow, and constraints.
.github/workflows/test-configs.yml	Adds CI build job that compiles the disk confirmation code path.

Review details

Suppressed comments (2)

hal/library_fs.c:176

• disk_trailer_open() uses fseek()/ftell() and a long size, which can truncate offsets/sizes on 32-bit hosts and mis-locate the trailer on devices/images >2GiB. Use fseeko()/ftello() with off_t instead.

    if (fseek(*fp, 0, SEEK_END) != 0 || (end = ftell(*fp)) < 0) {
        wolfBoot_printf("Cannot determine the size of %s\n", disk_dev);
        fclose(*fp);
        return -1;
    }

hal/library_fs.c:186

• Seeking to the computed trailer offset should also use fseeko() (with off_t) to avoid narrowing the offset via (long)*off on 32-bit hosts.

    if (fseek(*fp, (long)*off, SEEK_SET) != 0) {
        wolfBoot_printf("Cannot seek to the tail of %s\n", disk_dev);
        fclose(*fp);
        return -1;
    }

• Files reviewed: 10/10 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.