Skip to content

Add patina_sre crate (System Recovery Environment boot orchestrator)#91

Open
kat-perez wants to merge 1 commit into
OpenDevicePartnership:mainfrom
kat-perez:kat-perez/patina-sre
Open

Add patina_sre crate (System Recovery Environment boot orchestrator)#91
kat-perez wants to merge 1 commit into
OpenDevicePartnership:mainfrom
kat-perez:kat-perez/patina-sre

Conversation

@kat-perez
Copy link
Copy Markdown
Contributor

@kat-perez kat-perez commented May 12, 2026

Description

Adds a new `patina_sre` crate at `uefi/crates/patina_sre/` containing `SreBootManager` — a reference implementation of `patina_boot::BootOrchestrator` for ODP platforms shipping a System Recovery Environment alongside the main OS. The orchestrator is generic over a [`HotkeySource`] abstraction so vendors can wire platform-specific hotkey hardware while keeping the SRE flow itself portable.

The crate ships:

  • `SreBootManager<H: HotkeySource>` — runs the common BDS-phase sequencing (controller-connect / dispatch interleave, `EndOfDxe` and `ReadyToBoot` signals, console discovery), then branches between two boot paths based on the hotkey state.
  • Normal boot path — `patina_nvme::lock_partition_write` on the boot partition, then `patina_boot::helpers::boot_from_device_path` for the main OS.
  • SRE recovery path — `patina_partition::read_partition_file` to slurp the SRE WIM from the boot partition, write-lock the partition (best-effort: warns and continues if NVMe Pass-Thru is unavailable, so QEMU without BPWPS emulation still works), `patina_ram_disk::install` to publish the WIM as a virtual block device, and boot the RAM disk.
  • `HotkeySource` trait + two impls:
    • `AlwaysSre` — forces the SRE path. Useful for QEMU validation and unit tests.
    • `NeverSre` — forces the normal path. Useful for builds that don't yet have hotkey hardware wired.
      Platform vendors implement `HotkeySource` themselves to bridge their hotkey hardware (e.g. Surface's `MsButtonServicesProtocol`).

This supersedes patina#1492, which placed `SreBootManager` inside `patina_boot`. Per the reviewer thread on patina#1488, the SRE orchestrator is a platform-level component and doesn't belong in the generic `patina_boot` SDK crate.

Closes ODP-board #62 (`SreBootManager` skeleton), #63 (`HotkeySource` trait), and #68 (SRE boot path wiring).

  • Impacts functionality?
  • Impacts security?
  • Breaking change?
  • Includes tests?
  • Includes documentation?

How This Was Tested

`cargo test --lib` — all 9 tests pass:

```
test hotkey::tests::always_sre_returns_true ... ok
test hotkey::tests::never_sre_returns_false ... ok
test tests::test_new_constructs ... ok
test tests::test_new_with_always_sre ... ok
test tests::test_interleave_single_round_no_drivers_dispatched ... ok
test tests::test_interleave_dispatch_failure_propagates ... ok
test tests::test_interleave_stops_at_max_rounds ... ok
test tests::test_implements_boot_orchestrator ... ok
test tests::test_arc_dyn_construction ... ok
```

Coverage spans the interleave-connect-dispatch loop (single-round convergence, dispatch-error propagation, max-rounds graceful exit), the `HotkeySource` impls, `BootOrchestrator` trait conformance for both `SreBootManager` and `SreBootManager`, and `Arc` construction (matching the `BootDispatcher` consumption path).

End-to-end QEMU validation is a separate change on `patina-dxe-core-qemu` that wires `SreBootManager` into the Q35 platform component list and exercises both paths under `patina-qemu`.

Integration Instructions

Add `patina_sre` to your platform DXE core's component list, with a `HotkeySource` implementation appropriate to the platform:

```rust,ignore
use patina_boot::BootDispatcher;
use patina_sre::{NeverSre, SreBootManager};

Core::default()
.with_component(BootDispatcher::new(SreBootManager::new(
boot_partition_device_path,
main_os_device_path,
"\\SRE\\winvos.wim",
NeverSre, // replace with your platform's hotkey impl (e.g. SurfaceButtonHotkeySource)
)))
```

`patina`, `patina_boot`, `patina_nvme`, `patina_partition`, and `patina_ram_disk` are consumed as git dependencies because none of those releases are on crates.io yet. A `[patch]` block redirects transitive `patina` deps from upstream's `feature/patina-boot` onto a temporary combined branch (`kat-perez/sre-base` = `feature/patina-boot` + the EFI_RAM_DISK_PROTOCOL binding from patina#1490) so cargo sees one shared `patina` version across the dep tree. Once the corresponding patina release ships, the manifest moves to versioned crates.io references and downstream consumers won't need any patch glue.

Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull request overview

Adds a new uefi/crates/patina_sre crate providing SreBootManager, a reference patina_boot::BootOrchestrator implementation intended to drive a “normal boot” BDS-phase sequence for ODP platforms that ship an SRE alongside the main OS.

Changes:

  • Introduces SreBootManager with an interleave connect/dispatch loop plus a normal-boot execute() implementation.
  • Adds unit tests covering the connect/dispatch interleave behavior and trait-object construction.
  • Adds crate packaging/docs/tooling files (Cargo manifest, README, rust-toolchain, rustfmt config) and a crate-local lockfile.

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file
File Description
uefi/crates/patina_sre/src/lib.rs Implements SreBootManager, interleave helper, and unit tests.
uefi/crates/patina_sre/Cargo.toml Defines crate metadata and git-based dependencies for patina* crates.
uefi/crates/patina_sre/README.md Documents intended boot sequence and adoption guidance.
uefi/crates/patina_sre/rust-toolchain.toml Pins the nightly toolchain + UEFI targets/components for this crate.
uefi/crates/patina_sre/rustfmt.toml Sets formatting configuration for the crate.
uefi/crates/patina_sre/Cargo.lock Pins dependency resolution for the crate directory.

Comment thread uefi/crates/patina_sre/src/lib.rs Outdated
}

if let Err(e) = patina_nvme::lock_partition_write(boot_services, &self.boot_partition_path) {
log::error!("lock_partition_write failed: {:?}", e);
Comment thread uefi/crates/patina_sre/src/lib.rs Outdated
Comment on lines +119 to +126
match helpers::boot_from_device_path(boot_services, image_handle, &self.main_os_path) {
Ok(()) => log::warn!("Main OS boot returned control"),
Err(_) => log::warn!("Main OS boot failed"),
}

log::error!("SRE normal boot exhausted main OS path");
Err(EfiError::NotFound)
}
Comment on lines +103 to +105
if let Err(e) = helpers::signal_bds_phase_entry(boot_services) {
log::error!("signal_bds_phase_entry failed: {:?}", e);
}
Comment on lines +6 to +12
[package]
name = "patina_sre"
version = "0.1.0"
edition = "2024"
rust-version = "1.89"
license = "MIT"
repository = "https://github.com/OpenDevicePartnership/odp-platform-common"
@kat-perez kat-perez force-pushed the kat-perez/patina-sre branch 2 times, most recently from debca5c to b73e22a Compare May 12, 2026 18:59
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.

3 participants