From 14a244622876f79339ded9046786bddd34a1b260 Mon Sep 17 00:00:00 2001 From: Christina Quast Date: Fri, 13 Nov 2026 10:57:19 +0100 Subject: [PATCH] orchestrator: keep the self-update session in a boot stage record The new format crate holds the record the eRoT writes, the tried mark the boot stage writes before a trial jump, the handover, and select(), which picks the slot to start. The crate has no dependencies, so a boot stage outside the orchestrator links the same layout. RecordSession implements SelfUpdate over record copies A and B on Storage. Each transition writes the copy that does not hold the newest record, so a torn write damages only the copy the next read skips. confirm() writes the trial slot in as the confirmed slot, so from the confirm on, the boot stage starts the new image from the confirmed slot, and starts the trial slot only for a pending trial. The Committed session keeps the old confirmed slot as the previous slot, and a revert from Committed writes the previous slot back. The running() doc now says the answer holds for the whole boot, a confirm included. Signed-off-by: Christina Quast --- .../orchestrator/adapters/record/BUILD.bazel | 51 ++ .../adapters/record/format/crc32.rs | 48 ++ .../adapters/record/format/lib.rs | 31 + .../adapters/record/format/mark.rs | 106 +++ .../adapters/record/format/record.rs | 395 ++++++++++ .../adapters/record/format/select.rs | 381 ++++++++++ .../orchestrator/adapters/record/src/lib.rs | 24 + .../adapters/record/src/session.rs | 473 ++++++++++++ .../orchestrator/adapters/record/src/tests.rs | 688 ++++++++++++++++++ .../capabilities/src/self_update.rs | 12 +- 10 files changed, 2204 insertions(+), 5 deletions(-) create mode 100644 services/orchestrator/adapters/record/BUILD.bazel create mode 100644 services/orchestrator/adapters/record/format/crc32.rs create mode 100644 services/orchestrator/adapters/record/format/lib.rs create mode 100644 services/orchestrator/adapters/record/format/mark.rs create mode 100644 services/orchestrator/adapters/record/format/record.rs create mode 100644 services/orchestrator/adapters/record/format/select.rs create mode 100644 services/orchestrator/adapters/record/src/lib.rs create mode 100644 services/orchestrator/adapters/record/src/session.rs create mode 100644 services/orchestrator/adapters/record/src/tests.rs diff --git a/services/orchestrator/adapters/record/BUILD.bazel b/services/orchestrator/adapters/record/BUILD.bazel new file mode 100644 index 000000000..af9c6b0a5 --- /dev/null +++ b/services/orchestrator/adapters/record/BUILD.bazel @@ -0,0 +1,51 @@ +# Licensed under the Apache-2.0 license +# SPDX-License-Identifier: Apache-2.0 + +load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test") + +# The record, the tried mark, the handover and the slot choice. No +# dependencies, so a boot stage outside the orchestrator links it too. +rust_library( + name = "orchestrator_self_update_format", + srcs = [ + "format/crc32.rs", + "format/lib.rs", + "format/mark.rs", + "format/record.rs", + "format/select.rs", + ], + crate_root = "format/lib.rs", + edition = "2024", + visibility = ["//visibility:public"], +) + +# Host tests: build on the host platform, no kernel/QEMU. +rust_test( + name = "orchestrator_self_update_format_test", + crate = ":orchestrator_self_update_format", +) + +# `SelfUpdate` over the record on `util_io::Storage`. +rust_library( + name = "orchestrator_self_update_record", + srcs = [ + "src/lib.rs", + "src/session.rs", + "src/tests.rs", + ], + crate_root = "src/lib.rs", + edition = "2024", + visibility = ["//visibility:public"], + deps = [ + ":orchestrator_self_update_format", + "//services/orchestrator/capabilities:orchestrator_capabilities", + "//services/orchestrator/config:orchestrator_config", + "//util/io", + ], +) + +# Host tests: build on the host platform, no kernel/QEMU. +rust_test( + name = "orchestrator_self_update_record_test", + crate = ":orchestrator_self_update_record", +) diff --git a/services/orchestrator/adapters/record/format/crc32.rs b/services/orchestrator/adapters/record/format/crc32.rs new file mode 100644 index 000000000..eb3a561bd --- /dev/null +++ b/services/orchestrator/adapters/record/format/crc32.rs @@ -0,0 +1,48 @@ +// Licensed under the Apache-2.0 license +// SPDX-License-Identifier: Apache-2.0 + +//! CRC-32 (IEEE 802.3, reflected), bit by bit. +//! +//! The record and the mark are a few bytes each, so the bitwise loop runs +//! fast enough and saves the flash a lookup table takes. The boot stage and +//! the eRoT link this function, so both compute the same checksum. + +/// The reflected IEEE 802.3 polynomial. +const POLY: u32 = 0xEDB8_8320; + +/// CRC-32 of `bytes`, as zlib and Ethernet compute it. +#[must_use] +pub const fn crc32(bytes: &[u8]) -> u32 { + let mut crc = u32::MAX; + let mut i = 0; + while i < bytes.len() { + crc ^= bytes[i] as u32; + let mut bit = 0; + while bit < u8::BITS { + crc = if crc & 1 == 1 { + (crc >> 1) ^ POLY + } else { + crc >> 1 + }; + bit += 1; + } + i += 1; + } + !crc +} + +#[cfg(test)] +mod tests { + use super::*; + + // The check value every CRC-32/ISO-HDLC implementation publishes. + #[test] + fn matches_the_published_check_value() { + assert_eq!(crc32(b"123456789"), 0xCBF4_3926); + } + + #[test] + fn empty_input_gives_zero() { + assert_eq!(crc32(&[]), 0); + } +} diff --git a/services/orchestrator/adapters/record/format/lib.rs b/services/orchestrator/adapters/record/format/lib.rs new file mode 100644 index 000000000..1194928d8 --- /dev/null +++ b/services/orchestrator/adapters/record/format/lib.rs @@ -0,0 +1,31 @@ +// Licensed under the Apache-2.0 license +// SPDX-License-Identifier: Apache-2.0 + +//! The bytes the eRoT and its boot stage share for a self-update. +//! +//! The boot stage (ROM or bootloader) starts one image slot per boot. The +//! eRoT writes a [`Record`] that steers that choice: which slot is +//! confirmed, and the session of an update in flight. The boot stage reads +//! the record, picks a slot with [`select`], checks the signature and the +//! SVN floor of that slot, and hands the started slot and its SVN to the +//! image as a [`Handover`]. +//! +//! The crate has no dependencies and no I/O, so a boot stage outside the +//! orchestrator links it too, and the record layout has one definition. +//! +//! On storage that cannot write a record atomically, the eRoT keeps copies +//! A and B, writes the copy that does not hold the newest record, and reads +//! the newest copy that decodes ([`newest`]). The eRoT writes the record, +//! and the boot stage only reads it. + +#![cfg_attr(not(test), no_std)] + +mod crc32; +mod mark; +mod record; +mod select; + +pub use crc32::crc32; +pub use mark::{Handover, TriedMark, MARK_LEN}; +pub use record::{newest, CopyId, DecodeError, Phase, Record, Session, RECORD_LEN, RECORD_VERSION}; +pub use select::{pick_trial_slot, select, Start}; diff --git a/services/orchestrator/adapters/record/format/mark.rs b/services/orchestrator/adapters/record/format/mark.rs new file mode 100644 index 000000000..056ea17a7 --- /dev/null +++ b/services/orchestrator/adapters/record/format/mark.rs @@ -0,0 +1,106 @@ +// Licensed under the Apache-2.0 license +// SPDX-License-Identifier: Apache-2.0 + +//! What the boot stage writes for itself and what it hands to the image. + +use crate::crc32::crc32; + +/// Bytes the tried mark takes. +pub const MARK_LEN: usize = 12; + +/// Opens the tried mark, so an erased region reads as no mark. +const MARK_MAGIC: [u8; 4] = *b"OPTM"; + +const MAGIC_AT: usize = 0; +const COUNTER_AT: usize = 4; +const CRC_AT: usize = 8; +const _: () = assert!(CRC_AT + size_of::() == MARK_LEN); + +/// The counter of the record whose trial the boot stage started. +/// +/// Before the jump into the trial slot, the boot stage writes the mark into +/// a region that only the boot stage writes, reads the mark back and locks +/// the region until reset. A mark that holds the counter of the newest +/// record means the trial already ran, so the boot stage starts the +/// confirmed slot and each record write gets one trial boot. The eRoT does +/// not write or read the region: a new session is a new record write, and +/// its counter differs from the mark. +#[derive(Clone, Copy, PartialEq, Eq, Debug)] +pub struct TriedMark { + /// The counter of the record whose trial the boot stage started. + pub counter: u32, +} + +impl TriedMark { + /// The bytes of the mark: the counter little-endian, the checksum last. + #[must_use] + pub fn encode(&self) -> [u8; MARK_LEN] { + let mut bytes = [0; MARK_LEN]; + bytes[MAGIC_AT..COUNTER_AT].copy_from_slice(&MARK_MAGIC); + bytes[COUNTER_AT..CRC_AT].copy_from_slice(&self.counter.to_le_bytes()); + let crc = crc32(&bytes[..CRC_AT]); + bytes[CRC_AT..].copy_from_slice(&crc.to_le_bytes()); + bytes + } + + /// Reads the mark. `None` for an erased region, a torn write or any + /// other bytes that fail the magic or the checksum. + #[must_use] + pub fn decode(bytes: &[u8; MARK_LEN]) -> Option { + if bytes[MAGIC_AT..COUNTER_AT] != MARK_MAGIC { + return None; + } + let word = |at: usize| { + let mut word = [0; size_of::()]; + word.copy_from_slice(&bytes[at..at + size_of::()]); + u32::from_le_bytes(word) + }; + if crc32(&bytes[..CRC_AT]) != word(CRC_AT) { + return None; + } + Some(Self { + counter: word(COUNTER_AT), + }) + } +} + +/// What the boot stage tells the image it started. +/// +/// The boot stage checked the signature of the image before the jump and +/// read the SVN from its signed header, so both values come from a checked +/// image. The platform picks the mechanism that hands the values to the +/// image. +#[derive(Clone, Copy, PartialEq, Eq, Debug)] +pub struct Handover { + /// The slot the boot stage started. + pub started: u8, + /// The SVN from the signed header of the started image. + pub svn: u32, +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_mark_reads_back_as_written() { + let mark = TriedMark { counter: 41 }; + assert_eq!(TriedMark::decode(&mark.encode()), Some(mark)); + } + + #[test] + fn an_erased_region_holds_no_mark() { + assert_eq!(TriedMark::decode(&[0xFF; MARK_LEN]), None); + assert_eq!(TriedMark::decode(&[0; MARK_LEN]), None); + } + + #[test] + fn a_torn_mark_reads_as_no_mark() { + let full = TriedMark { counter: 41 }.encode(); + for cut in 0..MARK_LEN { + let mut bytes = [0xFF; MARK_LEN]; + bytes[..cut].copy_from_slice(&full[..cut]); + assert_eq!(TriedMark::decode(&bytes), None, "prefix of {cut} bytes"); + } + } +} diff --git a/services/orchestrator/adapters/record/format/record.rs b/services/orchestrator/adapters/record/format/record.rs new file mode 100644 index 000000000..afd495a7a --- /dev/null +++ b/services/orchestrator/adapters/record/format/record.rs @@ -0,0 +1,395 @@ +// Licensed under the Apache-2.0 license +// SPDX-License-Identifier: Apache-2.0 + +//! The record the eRoT writes and the boot stage reads. + +use crate::crc32::crc32; + +/// Bytes one copy of the record takes. +pub const RECORD_LEN: usize = 20; + +/// The layout version of the bytes below. A reader refuses a record with +/// another version, so a change to the layout bumps this value. +pub const RECORD_VERSION: u8 = 1; + +/// Opens every record copy, so erased or foreign flash does not decode. +const RECORD_MAGIC: [u8; 4] = *b"OPSU"; + +// Byte offsets inside one copy. Integers are little-endian. +const MAGIC_AT: usize = 0; +const VERSION_AT: usize = 4; +const PHASE_AT: usize = 5; +const CONFIRMED_AT: usize = 6; +const SLOT_AT: usize = 7; +const COUNTER_AT: usize = 8; +const SVN_AT: usize = 12; +const CRC_AT: usize = 16; +const _: () = assert!(CRC_AT + size_of::() == RECORD_LEN); + +// The phase byte. The slot byte holds the trial slot before the confirm and +// the previous slot after it. For a record with no session, `encode` writes +// zero into the slot and SVN bytes, and `decode` ignores them. +const NO_SESSION: u8 = 0; +const PREPARED: u8 = 1; +const TRIAL_PENDING: u8 = 2; +const COMMITTED: u8 = 3; + +/// Where a session stands, and the slot the session holds next to the +/// confirmed slot. `decode` refuses a record whose session slot equals the +/// confirmed slot. +#[derive(Clone, Copy, PartialEq, Eq, Debug)] +pub enum Phase { + /// The eRoT verified the image in `trial` and holds its SVN. The boot + /// stage still starts the confirmed slot. + Prepared { + /// The slot that holds the new image. + trial: u8, + }, + /// At the next boot, the boot stage starts `trial`, once. + TrialPending { + /// The slot that holds the new image. + trial: u8, + }, + /// The trial image ran and the eRoT confirmed it. The confirm wrote the + /// trial slot in as the confirmed slot, so the boot stage starts the new + /// image, and a revert writes `previous` back as the confirmed slot. + Committed { + /// The confirmed slot before the confirm, which holds the old image. + previous: u8, + }, +} + +impl Phase { + /// The slot the session holds next to the confirmed slot: the trial + /// slot, or after the confirm the previous slot. + #[must_use] + pub const fn slot(self) -> u8 { + match self { + Self::Prepared { trial } | Self::TrialPending { trial } => trial, + Self::Committed { previous } => previous, + } + } +} + +/// An update in flight: where the session stands and the SVN of the new +/// image. +#[derive(Clone, Copy, PartialEq, Eq, Debug)] +pub struct Session { + /// Where the session stands, with the slot it holds. + pub phase: Phase, + /// The SVN the eRoT read from the verified image. + pub svn: u32, +} + +impl Session { + /// The slot that holds the new image, before the confirm. `None` after + /// the confirm, which made the trial slot the confirmed slot. + #[must_use] + pub const fn trial(self) -> Option { + match self.phase { + Phase::Prepared { trial } | Phase::TrialPending { trial } => Some(trial), + Phase::Committed { .. } => None, + } + } +} + +/// One record: which slot is confirmed, and the session in flight if any. +#[derive(Clone, Copy, PartialEq, Eq, Debug)] +pub struct Record { + /// Counts writes. The copy with the higher counter, compared with + /// wrap-around, holds the newest record. + pub counter: u32, + /// The slot that holds the confirmed image. + pub confirmed: u8, + /// The update in flight. `None` when the eRoT has no update open. + pub session: Option, +} + +/// Why a copy did not decode. +#[derive(Clone, Copy, PartialEq, Eq, Debug)] +pub enum DecodeError { + /// The copy does not open with the record magic: erased or foreign + /// flash. + Magic, + /// The copy carries another layout version. + Version(u8), + /// The checksum does not match: a torn write or a flash fault. + Checksum, + /// The phase byte names no phase. + Phase(u8), + /// The session slot equals the confirmed slot. + SlotIsConfirmed, +} + +impl Record { + /// The record after this one: the counter one up, the given contents. + #[must_use] + pub const fn next(&self, confirmed: u8, session: Option) -> Self { + Self { + counter: self.counter.wrapping_add(1), + confirmed, + session, + } + } + + /// Whether the eRoT wrote `self` after `other`. Compares the counters + /// with wrap-around, so the order holds across a counter overflow as long + /// as the counters of copies A and B differ by less than `i32::MAX`. The + /// writer alternates the copies, so the counters differ by 1. + #[must_use] + pub const fn is_newer_than(&self, other: &Self) -> bool { + (self.counter.wrapping_sub(other.counter) as i32) > 0 + } + + /// Whether `known` accepts every slot the record names: the confirmed + /// slot, and the slot the session holds. + #[must_use] + pub fn names_known_slots(&self, mut known: impl FnMut(u8) -> bool) -> bool { + known(self.confirmed) + && self + .session + .is_none_or(|session| known(session.phase.slot())) + } + + /// Whether the record steers the boot stage to `slot`: the confirmed + /// slot, or the trial slot of a `TrialPending` session. The boot stage + /// starts the trial slot of a `Prepared` session or the previous slot of + /// a `Committed` session only when it walks. + #[must_use] + pub fn steers_to(&self, slot: u8) -> bool { + self.confirmed == slot + || self.session.is_some_and( + |session| matches!(session.phase, Phase::TrialPending { trial } if trial == slot), + ) + } + + /// The bytes of one copy: integers little-endian, the checksum last. + #[must_use] + pub fn encode(&self) -> [u8; RECORD_LEN] { + let mut bytes = [0; RECORD_LEN]; + bytes[MAGIC_AT..VERSION_AT].copy_from_slice(&RECORD_MAGIC); + bytes[VERSION_AT] = RECORD_VERSION; + bytes[CONFIRMED_AT] = self.confirmed; + bytes[COUNTER_AT..SVN_AT].copy_from_slice(&self.counter.to_le_bytes()); + if let Some(session) = self.session { + bytes[PHASE_AT] = match session.phase { + Phase::Prepared { .. } => PREPARED, + Phase::TrialPending { .. } => TRIAL_PENDING, + Phase::Committed { .. } => COMMITTED, + }; + bytes[SLOT_AT] = session.phase.slot(); + bytes[SVN_AT..CRC_AT].copy_from_slice(&session.svn.to_le_bytes()); + } else { + bytes[PHASE_AT] = NO_SESSION; + } + let crc = crc32(&bytes[..CRC_AT]); + bytes[CRC_AT..].copy_from_slice(&crc.to_le_bytes()); + bytes + } + + /// Reads one copy. Checks the magic, the version and the checksum + /// before any field, so a torn or erased copy reads as an error. + pub fn decode(bytes: &[u8; RECORD_LEN]) -> Result { + if bytes[MAGIC_AT..VERSION_AT] != RECORD_MAGIC { + return Err(DecodeError::Magic); + } + if bytes[VERSION_AT] != RECORD_VERSION { + return Err(DecodeError::Version(bytes[VERSION_AT])); + } + if crc32(&bytes[..CRC_AT]) != le_u32(bytes, CRC_AT) { + return Err(DecodeError::Checksum); + } + let confirmed = bytes[CONFIRMED_AT]; + let slot = bytes[SLOT_AT]; + let phase = match bytes[PHASE_AT] { + NO_SESSION => None, + PREPARED => Some(Phase::Prepared { trial: slot }), + TRIAL_PENDING => Some(Phase::TrialPending { trial: slot }), + COMMITTED => Some(Phase::Committed { previous: slot }), + other => return Err(DecodeError::Phase(other)), + }; + if phase.is_some() && slot == confirmed { + return Err(DecodeError::SlotIsConfirmed); + } + let session = phase.map(|phase| Session { + phase, + svn: le_u32(bytes, SVN_AT), + }); + Ok(Self { + counter: le_u32(bytes, COUNTER_AT), + confirmed, + session, + }) + } +} + +/// The little-endian `u32` at `at`. +fn le_u32(bytes: &[u8; RECORD_LEN], at: usize) -> u32 { + let mut word = [0; size_of::()]; + word.copy_from_slice(&bytes[at..at + size_of::()]); + u32::from_le_bytes(word) +} + +/// Copy A or copy B of the record, on storage that cannot write a record +/// atomically. +#[derive(Clone, Copy, PartialEq, Eq, Debug)] +pub enum CopyId { + /// The first copy. + A, + /// The second copy. + B, +} + +impl CopyId { + /// The copy the next write goes to when `self` holds the newest record. + #[must_use] + pub const fn other(self) -> Self { + match self { + Self::A => Self::B, + Self::B => Self::A, + } + } +} + +/// The newest valid record of copies A and B, and the copy that holds it. +/// +/// A writer always writes the copy that does not hold the newest record, so +/// a torn write damages only the copy this function then skips. `None` when +/// neither copy decodes. +#[must_use] +pub fn newest(a: Option, b: Option) -> Option<(CopyId, Record)> { + match (a, b) { + (Some(a), Some(b)) if b.is_newer_than(&a) => Some((CopyId::B, b)), + (Some(a), _) => Some((CopyId::A, a)), + (None, Some(b)) => Some((CopyId::B, b)), + (None, None) => None, + } +} + +#[cfg(test)] +mod tests { + use super::*; + + /// The counter of the record under test. + const COUNTER: u32 = 41; + + const PENDING: Record = Record { + counter: COUNTER, + confirmed: 0, + session: Some(Session { + phase: Phase::TrialPending { trial: 1 }, + svn: 7, + }), + }; + + /// `PENDING` after the confirm: slot 1 confirmed, slot 0 previous. + const COMMITTED: Record = Record { + counter: COUNTER + 1, + confirmed: 1, + session: Some(Session { + phase: Phase::Committed { previous: 0 }, + svn: 7, + }), + }; + + #[test] + fn a_record_reads_back_as_written() { + let idle = Record { + counter: 3, + confirmed: 1, + session: None, + }; + for record in [idle, PENDING, COMMITTED] { + assert_eq!(Record::decode(&record.encode()), Ok(record)); + } + } + + #[test] + fn erased_flash_does_not_decode() { + assert_eq!(Record::decode(&[0xFF; RECORD_LEN]), Err(DecodeError::Magic)); + assert_eq!(Record::decode(&[0; RECORD_LEN]), Err(DecodeError::Magic)); + } + + #[test] + fn a_flipped_bit_fails_the_checksum() { + let mut bytes = PENDING.encode(); + bytes[SVN_AT] ^= 1; + assert_eq!(Record::decode(&bytes), Err(DecodeError::Checksum)); + } + + // A torn write leaves a prefix of the new copy on erased flash. No + // prefix short of the whole copy decodes. + #[test] + fn no_torn_prefix_decodes() { + let full = PENDING.encode(); + for cut in 0..RECORD_LEN { + let mut bytes = [0xFF; RECORD_LEN]; + bytes[..cut].copy_from_slice(&full[..cut]); + assert!(Record::decode(&bytes).is_err(), "prefix of {cut} bytes"); + } + } + + #[test] + fn another_layout_version_is_refused() { + let mut bytes = PENDING.encode(); + bytes[VERSION_AT] = RECORD_VERSION + 1; + assert_eq!( + Record::decode(&bytes), + Err(DecodeError::Version(RECORD_VERSION + 1)) + ); + } + + #[test] + fn a_session_slot_on_the_confirmed_slot_is_refused() { + let pending = Record { + confirmed: 1, + ..PENDING + }; + let committed = Record { + confirmed: 0, + ..COMMITTED + }; + for record in [pending, committed] { + assert_eq!( + Record::decode(&record.encode()), + Err(DecodeError::SlotIsConfirmed) + ); + } + } + + #[test] + fn newest_picks_the_higher_counter_across_wrap_around() { + let old = Record { + counter: u32::MAX, + ..PENDING + }; + let new = old.next(0, None); + assert_eq!(new.counter, 0); + assert_eq!(newest(Some(old), Some(new)), Some((CopyId::B, new))); + assert_eq!(newest(Some(new), Some(old)), Some((CopyId::A, new))); + } + + #[test] + fn the_record_steers_to_the_session_slot_only_while_the_trial_is_pending() { + assert!(PENDING.steers_to(0)); + assert!(PENDING.steers_to(1)); + let prepared = Record { + session: Some(Session { + phase: Phase::Prepared { trial: 1 }, + svn: 7, + }), + ..PENDING + }; + assert!(prepared.steers_to(0)); + assert!(!prepared.steers_to(1)); + assert!(COMMITTED.steers_to(1)); + assert!(!COMMITTED.steers_to(0)); + } + + #[test] + fn newest_reads_the_one_valid_copy() { + assert_eq!(newest(None, Some(PENDING)), Some((CopyId::B, PENDING))); + assert_eq!(newest(Some(PENDING), None), Some((CopyId::A, PENDING))); + assert_eq!(newest(None, None), None); + } +} diff --git a/services/orchestrator/adapters/record/format/select.rs b/services/orchestrator/adapters/record/format/select.rs new file mode 100644 index 000000000..eab7dd733 --- /dev/null +++ b/services/orchestrator/adapters/record/format/select.rs @@ -0,0 +1,381 @@ +// Licensed under the Apache-2.0 license +// SPDX-License-Identifier: Apache-2.0 + +//! Which slot the boot stage starts, and which slot the next update takes. + +use crate::mark::TriedMark; +use crate::record::{Phase, Record}; + +/// What the boot stage does at this boot. +#[derive(Clone, Copy, PartialEq, Eq, Debug)] +pub enum Start { + /// Start `slot`. + /// + /// With a `mark`, `slot` is an untried trial: the boot stage writes the + /// mark, reads it back and locks the mark region before the jump, then + /// starts the trial watchdog. When the mark write or the read-back fails, + /// the boot stage calls [`select`] again and passes the mark it failed to + /// write. `select` then reads the trial as tried and starts the confirmed + /// slot or walks. + Slot { + /// The slot to start. + slot: u8, + /// The mark to write first, for a trial. + mark: Option, + }, + /// No slot passes its checks. The boot stage starts the golden image in + /// recovery mode. + Recovery, +} + +/// Picks the slot to start. +/// +/// `record` is the newest valid copy, `mark` the tried mark the boot stage +/// holds, `slots` the slot ids in layout order, and `passes` runs the +/// signature check and the SVN floor check on one slot. `select` returns +/// only a slot that passes `passes`, and calls `passes` at most once per +/// slot. +/// +/// 1. For an untried `TrialPending` session, the boot stage starts the trial +/// slot, with a mark. +/// 2. Otherwise the boot stage starts the confirmed slot. After the confirm, +/// the confirmed slot holds the new image. +/// 3. When the slot from the steps above fails its checks, or no record +/// decodes, or the record names a slot outside `slots`, the boot stage +/// walks `slots` in order and starts the first slot that passes. The walk +/// skips the trial slot of a `TrialPending` session, which gets one try. +/// 4. When no slot passes, the boot stage starts the golden image in +/// recovery mode. +pub fn select( + record: Option, + mark: Option, + slots: I, + mut passes: impl FnMut(u8) -> bool, +) -> Start +where + I: IntoIterator + Clone, +{ + let record = record.filter(|record| { + record.names_known_slots(|slot| slots.clone().into_iter().any(|known| known == slot)) + }); + // The slots the steps before the walk checked and saw fail, and the + // trial slot that already had its try. The walk starts neither. + let mut skip_trial = None; + let mut skip_confirmed = None; + if let Some(record) = record { + if let Some(Phase::TrialPending { trial }) = record.session.map(|session| session.phase) { + skip_trial = Some(trial); + let tried = mark.is_some_and(|mark| mark.counter == record.counter); + if !tried && passes(trial) { + return Start::Slot { + slot: trial, + mark: Some(TriedMark { + counter: record.counter, + }), + }; + } + } + if passes(record.confirmed) { + return Start::Slot { + slot: record.confirmed, + mark: None, + }; + } + skip_confirmed = Some(record.confirmed); + } + for slot in slots { + if Some(slot) != skip_trial && Some(slot) != skip_confirmed && passes(slot) { + return Start::Slot { slot, mark: None }; + } + } + Start::Recovery +} + +/// The slot a new update writes its image into: the first slot in layout +/// order that is not the confirmed slot of `record`, not the slot running +/// now, and not the previous slot of a `Committed` session. +/// +/// The running slot differs from the confirmed slot while an unconfirmed +/// trial runs. Writing into the running slot would replace the image the +/// eRoT executes, and writing into the previous slot would replace the +/// old image, whose slot a revert from `Committed` writes back as +/// confirmed, so the pick skips both. `None` means no slot is left. +#[must_use] +pub fn pick_trial_slot( + record: &Record, + running: u8, + slots: impl IntoIterator, +) -> Option { + let previous = match record.session.map(|session| session.phase) { + Some(Phase::Committed { previous }) => Some(previous), + _ => None, + }; + slots + .into_iter() + .find(|&slot| slot != record.confirmed && slot != running && Some(slot) != previous) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::record::Session; + + const SLOTS: [u8; 2] = [0, 1]; + const THREE: [u8; 3] = [0, 1, 2]; + /// A slot id no layout in these tests holds. + const UNKNOWN_SLOT: u8 = 5; + /// The counter of the record under test. + const COUNTER: u32 = 41; + + const fn record(confirmed: u8, phase: Option) -> Record { + Record { + counter: COUNTER, + confirmed, + session: match phase { + Some(phase) => Some(Session { phase, svn: 7 }), + None => None, + }, + } + } + + const fn start(slot: u8) -> Start { + Start::Slot { slot, mark: None } + } + + const fn trial(slot: u8) -> Start { + Start::Slot { + slot, + mark: Some(TriedMark { counter: COUNTER }), + } + } + + const TRIED: Option = Some(TriedMark { counter: COUNTER }); + const STALE: Option = Some(TriedMark { + counter: COUNTER - 1, + }); + + struct Case { + name: &'static str, + record: Option, + mark: Option, + slots: &'static [u8], + failing: &'static [u8], + expect: Start, + } + + #[test] + fn selects_the_decided_slot_in_every_case() { + let prepared = Some(Phase::Prepared { trial: 1 }); + let pending = Some(Phase::TrialPending { trial: 1 }); + let committed = Some(Phase::Committed { previous: 0 }); + let cases = [ + Case { + name: "no record: the first slot that passes", + record: None, + mark: None, + slots: &SLOTS, + failing: &[], + expect: start(0), + }, + Case { + name: "no record, first slot fails: the walk goes on", + record: None, + mark: None, + slots: &SLOTS, + failing: &[0], + expect: start(1), + }, + Case { + name: "no record, every slot fails: recovery", + record: None, + mark: None, + slots: &SLOTS, + failing: &[0, 1], + expect: Start::Recovery, + }, + Case { + name: "no session: the confirmed slot, not the first one", + record: Some(record(1, None)), + mark: None, + slots: &SLOTS, + failing: &[], + expect: start(1), + }, + Case { + name: "prepared: the confirmed slot", + record: Some(record(0, prepared)), + mark: None, + slots: &SLOTS, + failing: &[], + expect: start(0), + }, + Case { + name: "prepared, confirmed fails: the walk starts the trial slot", + record: Some(record(0, prepared)), + mark: None, + slots: &SLOTS, + failing: &[0], + expect: start(1), + }, + Case { + name: "pending, no mark: the trial, with a mark", + record: Some(record(0, pending)), + mark: None, + slots: &SLOTS, + failing: &[], + expect: trial(1), + }, + Case { + name: "pending, mark from an earlier record: the trial", + record: Some(record(0, pending)), + mark: STALE, + slots: &SLOTS, + failing: &[], + expect: trial(1), + }, + Case { + name: "pending, already tried: the confirmed slot", + record: Some(record(0, pending)), + mark: TRIED, + slots: &SLOTS, + failing: &[], + expect: start(0), + }, + Case { + name: "pending, trial fails its checks: the confirmed slot", + record: Some(record(0, pending)), + mark: None, + slots: &SLOTS, + failing: &[1], + expect: start(0), + }, + Case { + name: "pending and tried, confirmed fails: the walk skips the trial", + record: Some(record(0, pending)), + mark: TRIED, + slots: &SLOTS, + failing: &[0], + expect: Start::Recovery, + }, + Case { + name: "pending and tried, confirmed fails: the walk finds a third slot", + record: Some(record(0, pending)), + mark: TRIED, + slots: &THREE, + failing: &[0], + expect: start(2), + }, + Case { + name: "committed: the confirmed slot, which holds the new image", + record: Some(record(1, committed)), + mark: TRIED, + slots: &SLOTS, + failing: &[], + expect: start(1), + }, + Case { + name: "committed, confirmed fails: the walk starts the previous slot", + record: Some(record(1, committed)), + mark: None, + slots: &SLOTS, + failing: &[1], + expect: start(0), + }, + Case { + name: "committed, confirmed fails: the walk starts a slot before the previous slot", + record: Some(record(2, Some(Phase::Committed { previous: 1 }))), + mark: None, + slots: &THREE, + failing: &[2], + expect: start(0), + }, + Case { + name: "committed, both fail: recovery", + record: Some(record(1, committed)), + mark: None, + slots: &SLOTS, + failing: &[0, 1], + expect: Start::Recovery, + }, + Case { + name: "confirmed slot fails: the walk", + record: Some(record(1, None)), + mark: None, + slots: &SLOTS, + failing: &[1], + expect: start(0), + }, + Case { + name: "record names an unknown confirmed slot: the walk", + record: Some(record(UNKNOWN_SLOT, None)), + mark: None, + slots: &SLOTS, + failing: &[], + expect: start(0), + }, + Case { + name: "record names an unknown trial slot: the walk", + record: Some(record( + 1, + Some(Phase::TrialPending { + trial: UNKNOWN_SLOT, + }), + )), + mark: None, + slots: &SLOTS, + failing: &[], + expect: start(0), + }, + Case { + name: "record names an unknown previous slot: the walk", + record: Some(record( + 1, + Some(Phase::Committed { + previous: UNKNOWN_SLOT, + }), + )), + mark: None, + slots: &SLOTS, + failing: &[], + expect: start(0), + }, + ]; + for case in cases { + let mut checked = [0; THREE.len()]; + let got = select(case.record, case.mark, case.slots.iter().copied(), |slot| { + checked[usize::from(slot)] += 1; + !case.failing.contains(&slot) + }); + assert_eq!(got, case.expect, "{}", case.name); + assert!( + checked.iter().all(|&count| count <= 1), + "{}: a slot was checked twice", + case.name + ); + } + } + + #[test] + fn the_trial_slot_is_the_first_free_one() { + assert_eq!(pick_trial_slot(&record(0, None), 0, SLOTS), Some(1)); + assert_eq!(pick_trial_slot(&record(1, None), 1, SLOTS), Some(0)); + assert_eq!(pick_trial_slot(&record(0, None), 0, THREE), Some(1)); + } + + // An unconfirmed trial runs from slot 1 while slot 0 stays confirmed. + // The next update must not overwrite either. + #[test] + fn the_trial_slot_skips_the_running_slot() { + assert_eq!(pick_trial_slot(&record(0, None), 1, SLOTS), None); + assert_eq!(pick_trial_slot(&record(0, None), 1, THREE), Some(2)); + } + + // After the confirm, slot 1 is confirmed and runs, and slot 0 holds the + // image a revert writes back. The next update must not overwrite slot 0. + #[test] + fn the_trial_slot_skips_the_previous_slot() { + let committed = record(1, Some(Phase::Committed { previous: 0 })); + assert_eq!(pick_trial_slot(&committed, 1, SLOTS), None); + assert_eq!(pick_trial_slot(&committed, 1, THREE), Some(2)); + } +} diff --git a/services/orchestrator/adapters/record/src/lib.rs b/services/orchestrator/adapters/record/src/lib.rs new file mode 100644 index 000000000..b77b6780e --- /dev/null +++ b/services/orchestrator/adapters/record/src/lib.rs @@ -0,0 +1,24 @@ +// Licensed under the Apache-2.0 license +// SPDX-License-Identifier: Apache-2.0 + +//! [`SelfUpdate`](orchestrator_capabilities::SelfUpdate) for an eRoT whose +//! boot stage reads a record the eRoT writes. +//! +//! The record format, the tried mark, the handover and the slot choice of +//! the boot stage live in `orchestrator_self_update_format`, which the boot +//! stage links too. This crate adds the storage side: it reads record +//! copies A and B at boot, reconciles them with the slot the boot stage +//! started, and writes one copy per transition. +//! +//! The pending mark is part of the record: `set_trial_pending` writes the +//! `TrialPending` phase, and the boot stage reads that phase. The trial +//! watchdog, the lock on the mark region and the handover mechanism belong +//! to the boot stage and the board, not to this crate. + +#![cfg_attr(not(test), no_std)] + +mod session; +#[cfg(test)] +mod tests; + +pub use session::{Found, RecordCopies, RecordError, RecordSession, Rewrite}; diff --git a/services/orchestrator/adapters/record/src/session.rs b/services/orchestrator/adapters/record/src/session.rs new file mode 100644 index 000000000..757728f10 --- /dev/null +++ b/services/orchestrator/adapters/record/src/session.rs @@ -0,0 +1,473 @@ +// Licensed under the Apache-2.0 license +// SPDX-License-Identifier: Apache-2.0 + +//! [`SelfUpdate`] over record copies A and B on [`Storage`]. + +use orchestrator_capabilities::{BootSelection, RunningImage, SelfUpdate, SelfUpdateState, Svn}; +use orchestrator_config::{ImageLayout, SlotId}; +use orchestrator_self_update_format::{ + newest, pick_trial_slot, CopyId, Handover, Phase, Record, Session, RECORD_LEN, +}; +use util_io::Storage; + +/// Where record copies A and B sit on the storage. +/// +/// [`Storage`] erases on the first write into an erase block and hides the +/// erase from the caller, so copies A and B must sit in different erase +/// blocks: a write into one copy then cannot wipe the other. +#[derive(Clone, Copy, Debug)] +pub struct RecordCopies { + a: usize, + b: usize, +} + +impl RecordCopies { + /// Places copy A at offset `a` and copy B at offset `b`. Const, so a bad + /// board table fails the build. + /// + /// # Panics + /// + /// Panics when a copy does not fit one erase block, when an offset does + /// not start an erase block, or when both copies share an erase block. + #[must_use] + pub const fn new(a: usize, b: usize, erase_block: usize) -> Self { + assert!( + RECORD_LEN <= erase_block, + "a record copy must fit one erase block" + ); + assert!( + a % erase_block == 0 && b % erase_block == 0, + "each record copy must start an erase block" + ); + assert!( + a != b, + "the record copies must sit in different erase blocks" + ); + Self { a, b } + } + + const fn offset(&self, copy: CopyId) -> usize { + match copy { + CopyId::A => self.a, + CopyId::B => self.b, + } + } +} + +/// What [`RecordSession::open`] found on the storage, for the board to log. +#[derive(Clone, Copy, PartialEq, Eq, Debug)] +pub enum Found { + /// Both copies decode. + Intact, + /// One copy decodes and the other does not: a torn write, a flash fault, + /// or a new part after the first record write, which fills copy A. The + /// next write goes to the copy that does not decode. + OneValidCopy, + /// The eRoT wrote a fresh record, with the started slot as the confirmed + /// slot and no session. + Rewritten(Rewrite), +} + +/// Why [`RecordSession::open`] wrote a fresh record. +#[derive(Clone, Copy, PartialEq, Eq, Debug)] +pub enum Rewrite { + /// Neither copy decodes: a new part, both copies damaged, or a record + /// of another layout version, which `open` overwrites. The boot stage + /// walked the slots. + NoValidCopy, + /// The newest record names a slot outside the layout. + UnknownSlot, + /// The boot stage started a slot the record does not steer to: the slots + /// the record steers to failed their checks and the boot stage walked. + /// The walk can start the trial slot of a `Prepared` session or the + /// previous slot of a `Committed` session, which then becomes the + /// confirmed slot. The fresh record holds no session. + Walked, +} + +/// Why a [`RecordSession`] call failed. +#[derive(Clone, Copy, PartialEq, Eq, Debug)] +pub enum RecordError { + /// The storage failed. The record in RAM keeps the value it had, so a + /// retry writes the same copy. The flash can already hold the new + /// record, when the write landed and only the completion failed: + /// `state` then reports the old state until the next boot reads the + /// flash. + Storage(E), + /// The called transition starts from a state other than the state the + /// record holds, for example `set_trial_pending` while the record holds + /// `Idle`. The variant carries the state the record holds. + WrongState(SelfUpdateState), + /// The boot stage started the confirmed slot in this boot, and the image + /// in the trial slot did not run, so `confirm` refuses to write the trial + /// slot in as the confirmed slot. + TrialNotRunning, + /// Every slot is the confirmed slot, the slot running now or the previous + /// slot of a `Committed` session, so an update has no slot to write its + /// image into. + NoFreeSlot, + /// The handover names a slot outside the layout. + UnknownStartedSlot(SlotId), +} + +impl From for RecordError { + fn from(err: E) -> Self { + Self::Storage(err) + } +} + +impl core::fmt::Display for RecordError { + fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { + match self { + Self::Storage(err) => write!(f, "self-update record storage: {err:?}"), + Self::WrongState(state) => { + write!(f, "self-update transition not allowed from {state:?}") + } + Self::NoFreeSlot => f.write_str("no slot is free for a self-update"), + Self::TrialNotRunning => { + f.write_str("the boot stage started the confirmed slot, so confirm has no trial") + } + Self::UnknownStartedSlot(slot) => { + write!( + f, + "the boot stage started slot {} outside the layout", + slot.0 + ) + } + } + } +} + +impl core::error::Error for RecordError {} + +/// The self-update session of the eRoT, kept in record copies A and B. +/// +/// [`open`](Self::open) reads both copies once per boot and keeps the +/// newest record in RAM, so [`state`](SelfUpdate::state) and +/// [`running`](SelfUpdate::running) read no storage. Each transition writes +/// the copy that does not hold the newest record, with the counter one up, +/// in a separate storage session, and waits for the write to finish. A +/// transition the record already reflects writes nothing. +pub struct RecordSession { + storage: S, + copies: RecordCopies, + layout: ImageLayout, + handover: Handover, + /// What [`running`](SelfUpdate::running) answers, fixed at + /// [`open`](Self::open) so a confirm, a revert or a complete in this boot + /// does not change the answer. + selected: BootSelection, + record: Record, + newest: CopyId, +} + +impl RecordSession { + /// Reads the record and reconciles it with the slot the boot stage + /// started. + /// + /// Writes a fresh record, with the started slot confirmed and no + /// session, when no copy decodes, when the record names a slot outside + /// `layout`, or when the record does not steer the boot stage to the + /// started slot, so the boot stage walked. [`Found`] says which + /// happened. + /// + /// # Errors + /// + /// [`RecordError::UnknownStartedSlot`] when `handover` names a slot + /// outside `layout`, and [`RecordError::Storage`] when a read or the + /// fresh write fails. + pub fn open( + mut storage: S, + copies: RecordCopies, + layout: ImageLayout, + handover: Handover, + ) -> Result<(Self, Found), RecordError> { + if !in_layout(&layout, handover.started) { + return Err(RecordError::UnknownStartedSlot(SlotId(handover.started))); + } + let (a, b) = read_copies(&mut storage, copies)?; + let one_valid = a.is_some() != b.is_some(); + let Some((newest_copy, record)) = newest(a, b) else { + // No copy decodes. Passing copy B as the newest sends the first + // write to copy A. + let empty = Record { + counter: 0, + confirmed: handover.started, + session: None, + }; + return Self::rewrite(storage, copies, layout, handover, empty, CopyId::B) + .map(|session| (session, Found::Rewritten(Rewrite::NoValidCopy))); + }; + let rewrite = if !record.names_known_slots(|slot| in_layout(&layout, slot)) { + Rewrite::UnknownSlot + } else if !record.steers_to(handover.started) { + Rewrite::Walked + } else { + // The image of the session sits in the trial slot of a pending + // trial, and in the confirmed slot once the confirm wrote the + // trial slot in as confirmed. + let runs_session_image = match record.session.map(|session| session.phase) { + Some(Phase::TrialPending { trial }) => handover.started == trial, + Some(Phase::Committed { .. }) => handover.started == record.confirmed, + _ => false, + }; + let selected = if runs_session_image { + BootSelection::Trial + } else { + BootSelection::Confirmed + }; + let session = Self { + storage, + copies, + layout, + handover, + selected, + record, + newest: newest_copy, + }; + let found = if one_valid { + Found::OneValidCopy + } else { + Found::Intact + }; + return Ok((session, found)); + }; + Self::rewrite(storage, copies, layout, handover, record, newest_copy) + .map(|session| (session, Found::Rewritten(rewrite))) + } + + /// The slot the next [`prepare`](SelfUpdate::prepare) records as the + /// trial slot, so board code writes the image there. `None` when every + /// slot is the confirmed slot, the slot running now or the previous slot + /// of a `Committed` session. + #[must_use] + pub fn next_trial_slot(&self) -> Option { + pick_trial_slot( + &self.record, + self.handover.started, + self.layout.slots().iter().map(|slot| slot.id().0), + ) + .map(SlotId) + } + + /// The trial slot of the session in flight. `None` with no session, and + /// after the confirm, which made the trial slot the confirmed slot. + #[must_use] + pub fn trial_slot(&self) -> Option { + self.record.session.and_then(Session::trial).map(SlotId) + } + + /// Adopts the slot the boot stage started when no copy decodes, the + /// record names a slot outside the layout, or the boot stage walked: + /// writes the record after `base` with the started slot confirmed and no + /// session. + fn rewrite( + storage: S, + copies: RecordCopies, + layout: ImageLayout, + handover: Handover, + base: Record, + newest: CopyId, + ) -> Result> { + let mut session = Self { + storage, + copies, + layout, + handover, + selected: BootSelection::Confirmed, + record: base, + newest, + }; + session.write(handover.started, None)?; + Ok(session) + } + + /// Writes the record after the current one into the copy that does not + /// hold it. Updates the record in RAM only once the write is durable. + fn write( + &mut self, + confirmed: u8, + session: Option, + ) -> Result<(), RecordError> { + let record = self.record.next(confirmed, session); + let target = self.newest.other(); + self.storage.open()?; + let written = write_and_wait( + &mut self.storage, + self.copies.offset(target), + &record.encode(), + ); + let closed = self.storage.close(); + written?; + closed?; + self.record = record; + self.newest = target; + Ok(()) + } + + /// Hands the storage back, for a test that simulates a reset. + #[cfg(test)] + pub(crate) fn into_storage(self) -> S { + self.storage + } + + #[cfg(test)] + pub(crate) fn storage(&self) -> &S { + &self.storage + } + + #[cfg(test)] + pub(crate) fn storage_mut(&mut self) -> &mut S { + &mut self.storage + } +} + +impl SelfUpdate for RecordSession +where + S::Error: core::fmt::Debug, +{ + type Error = RecordError; + + fn state(&self) -> Result { + Ok(state_of(&self.record)) + } + + fn running(&self) -> Result { + Ok(RunningImage { + selected: self.selected, + svn: Some(Svn(self.handover.svn)), + }) + } + + fn prepare(&mut self, svn: Svn) -> Result<(), Self::Error> { + let trial = self.next_trial_slot().ok_or(RecordError::NoFreeSlot)?; + let session = Session { + phase: Phase::Prepared { trial: trial.0 }, + svn: svn.0, + }; + if self.record.session == Some(session) { + return Ok(()); + } + self.write(self.record.confirmed, Some(session)) + } + + fn set_trial_pending(&mut self) -> Result<(), Self::Error> { + match self.record.session { + Some(Session { + phase: Phase::Prepared { trial }, + svn, + }) => self.write( + self.record.confirmed, + Some(Session { + phase: Phase::TrialPending { trial }, + svn, + }), + ), + Some(Session { + phase: Phase::TrialPending { .. }, + .. + }) => Ok(()), + _ => Err(RecordError::WrongState(state_of(&self.record))), + } + } + + fn confirm(&mut self) -> Result<(), Self::Error> { + match self.record.session { + // The trial slot becomes the confirmed slot, and the session + // keeps the old confirmed slot so a revert can write it back. + Some(Session { + phase: Phase::TrialPending { trial }, + svn, + }) => { + if trial != self.handover.started { + return Err(RecordError::TrialNotRunning); + } + self.write( + trial, + Some(Session { + phase: Phase::Committed { + previous: self.record.confirmed, + }, + svn, + }), + ) + } + Some(Session { + phase: Phase::Committed { .. }, + .. + }) => Ok(()), + _ => Err(RecordError::WrongState(state_of(&self.record))), + } + } + + fn complete(&mut self) -> Result<(), Self::Error> { + match self.record.session { + Some(Session { + phase: Phase::Committed { .. }, + .. + }) => self.write(self.record.confirmed, None), + None => Ok(()), + Some(_) => Err(RecordError::WrongState(state_of(&self.record))), + } + } + + fn revert(&mut self) -> Result<(), Self::Error> { + match self.record.session { + Some(Session { + phase: Phase::Committed { previous }, + .. + }) => self.write(previous, None), + Some(_) => self.write(self.record.confirmed, None), + None => Ok(()), + } + } +} + +/// The session state a record holds. +fn state_of(record: &Record) -> SelfUpdateState { + match record.session { + None => SelfUpdateState::Idle, + Some(session) => { + let svn = Svn(session.svn); + match session.phase { + Phase::Prepared { .. } => SelfUpdateState::Prepared { svn }, + Phase::TrialPending { .. } => SelfUpdateState::TrialPending { svn }, + Phase::Committed { .. } => SelfUpdateState::Committed { svn }, + } + } + } +} + +fn in_layout(layout: &ImageLayout, slot: u8) -> bool { + layout.slots().iter().any(|known| known.id().0 == slot) +} + +/// Reads and decodes both copies in one storage session. +fn read_copies( + storage: &mut S, + copies: RecordCopies, +) -> Result<(Option, Option), S::Error> { + storage.open()?; + let mut a = [0; RECORD_LEN]; + let mut b = [0; RECORD_LEN]; + let read = storage + .read_at(copies.offset(CopyId::A), &mut a) + .and_then(|()| storage.read_at(copies.offset(CopyId::B), &mut b)); + let closed = storage.close(); + read?; + closed?; + Ok((Record::decode(&a).ok(), Record::decode(&b).ok())) +} + +/// Writes `bytes` at `offset` and polls until the write is durable. +fn write_and_wait( + storage: &mut S, + offset: usize, + bytes: &[u8], +) -> Result<(), S::Error> { + storage.start_write(offset, bytes)?; + while storage.is_busy() { + core::hint::spin_loop(); + } + storage.complete_write() +} diff --git a/services/orchestrator/adapters/record/src/tests.rs b/services/orchestrator/adapters/record/src/tests.rs new file mode 100644 index 000000000..7919ecfc1 --- /dev/null +++ b/services/orchestrator/adapters/record/src/tests.rs @@ -0,0 +1,688 @@ +// Licensed under the Apache-2.0 license +// SPDX-License-Identifier: Apache-2.0 + +use orchestrator_capabilities::{ + trial_outcome, BootSelection, RunningImage, SelfUpdate, SelfUpdateState, Svn, TrialOutcome, +}; +use orchestrator_config::{ImageLayout, Region, Slot, SlotId}; +use orchestrator_self_update_format::{ + newest, select, Handover, Record, Start, TriedMark, RECORD_LEN, +}; +use util_io::Storage; + +use crate::{Found, RecordCopies, RecordError, RecordSession, Rewrite}; + +/// The erase block of the RAM flash. +const BLOCK: usize = 64; +/// An erase block per record copy. +const FLASH_LEN: usize = 2 * BLOCK; +const COPY_A: usize = 0; +const COPY_B: usize = BLOCK; +const COPIES: RecordCopies = RecordCopies::new(COPY_A, COPY_B, BLOCK); +/// How many polls of `is_busy` answer `true` before a write finishes. +const POLLS_PER_WRITE: usize = 2; +/// A slot id neither layout in these tests holds. +const UNKNOWN_SLOT: u8 = 5; + +/// The image slots, each in a separate region. +const SLOT_LEN: u32 = 0x1_0000; +static TWO: [Slot; 2] = [ + Slot::new(SlotId(0), Region::new(0, SLOT_LEN)), + Slot::new(SlotId(1), Region::new(SLOT_LEN, SLOT_LEN)), +]; +static THREE: [Slot; 3] = [ + Slot::new(SlotId(0), Region::new(0, SLOT_LEN)), + Slot::new(SlotId(1), Region::new(SLOT_LEN, SLOT_LEN)), + Slot::new(SlotId(2), Region::new(2 * SLOT_LEN, SLOT_LEN)), +]; +const LAYOUT: ImageLayout = ImageLayout::new(&TWO, None); +const LAYOUT_THREE: ImageLayout = ImageLayout::new(&THREE, None); + +/// The SVN of the image on the part before the update. +const OLD: Svn = Svn(3); +/// The SVN of the update. +const NEW: Svn = Svn(7); + +#[derive(Clone, Copy, PartialEq, Eq, Debug)] +enum FlashError { + NoSession, + AlreadyOpen, + Busy, + NotBusy, + OutOfBounds, + WrittenTwice, + /// The write failed before it touched the flash. + Refused, + /// Power went away during the write. + PowerLost, +} + +/// RAM that behaves like NOR flash behind [`Storage`]: the first write into +/// an erase block in a session erases the whole block, and no byte takes a +/// second write in one session. +struct RamFlash { + bytes: [u8; FLASH_LEN], + open: bool, + busy_polls: Option, + erased: [bool; FLASH_LEN / BLOCK], + written: [bool; FLASH_LEN], + /// Counts the `start_write` calls the flash accepted. + writes: usize, + /// Refuses the next `start_write`. + refuse_next: bool, + /// Cuts the next write after this many bytes and fails it. + cut_next: Option, + cut: bool, +} + +impl RamFlash { + fn erased() -> Self { + Self { + bytes: [0xFF; FLASH_LEN], + open: false, + busy_polls: None, + erased: [false; FLASH_LEN / BLOCK], + written: [false; FLASH_LEN], + writes: 0, + refuse_next: false, + cut_next: None, + cut: false, + } + } + + /// Power goes away and comes back: the flash keeps its bytes and loses + /// the session. + fn power_cycle(mut self) -> Self { + self.open = false; + self.busy_polls = None; + self.cut = false; + self + } +} + +impl Storage for RamFlash { + type Error = FlashError; + + fn open(&mut self) -> Result<(), FlashError> { + if self.open { + return Err(FlashError::AlreadyOpen); + } + self.open = true; + self.erased = [false; FLASH_LEN / BLOCK]; + self.written = [false; FLASH_LEN]; + Ok(()) + } + + fn read_at(&mut self, offset: usize, buf: &mut [u8]) -> Result<(), FlashError> { + if !self.open { + return Err(FlashError::NoSession); + } + if self.busy_polls.is_some() { + return Err(FlashError::Busy); + } + let end = offset + buf.len(); + buf.copy_from_slice(self.bytes.get(offset..end).ok_or(FlashError::OutOfBounds)?); + Ok(()) + } + + fn start_write(&mut self, offset: usize, data: &[u8]) -> Result<(), FlashError> { + if !self.open { + return Err(FlashError::NoSession); + } + if self.busy_polls.is_some() { + return Err(FlashError::Busy); + } + if core::mem::take(&mut self.refuse_next) { + return Err(FlashError::Refused); + } + let end = offset + data.len(); + if end > FLASH_LEN { + return Err(FlashError::OutOfBounds); + } + if self.written[offset..end].iter().any(|&w| w) { + return Err(FlashError::WrittenTwice); + } + for block in offset / BLOCK..=(end - 1) / BLOCK { + if !self.erased[block] { + self.bytes[block * BLOCK..(block + 1) * BLOCK].fill(0xFF); + self.erased[block] = true; + } + } + let kept = self.cut_next.take().map_or(data.len(), |cut| { + self.cut = true; + cut + }); + self.bytes[offset..offset + kept].copy_from_slice(&data[..kept]); + self.written[offset..end].fill(true); + self.writes += 1; + self.busy_polls = Some(POLLS_PER_WRITE); + Ok(()) + } + + fn is_busy(&mut self) -> bool { + match self.busy_polls { + Some(0) | None => false, + Some(left) => { + self.busy_polls = Some(left - 1); + true + } + } + } + + fn complete_write(&mut self) -> Result<(), FlashError> { + match self.busy_polls { + Some(0) => { + self.busy_polls = None; + if self.cut { + Err(FlashError::PowerLost) + } else { + Ok(()) + } + } + Some(_) => Err(FlashError::Busy), + None => Err(FlashError::NotBusy), + } + } + + fn close(&mut self) -> Result<(), FlashError> { + if !self.open { + return Err(FlashError::NoSession); + } + if self.busy_polls.is_some() { + return Err(FlashError::Busy); + } + self.open = false; + Ok(()) + } +} + +/// The boot stage started `slot` at `svn`. +const fn started(slot: u8, svn: Svn) -> Handover { + Handover { + started: slot, + svn: svn.0, + } +} + +/// The session after a boot of `handover` on `flash`. +fn boot(flash: RamFlash, handover: Handover) -> (RecordSession, Found) { + RecordSession::open(flash.power_cycle(), COPIES, LAYOUT, handover).expect("the record opens") +} + +/// Resets the part: the storage keeps its bytes and the boot stage starts +/// `handover`. +fn reset(session: RecordSession, handover: Handover) -> RecordSession { + boot(session.into_storage(), handover).0 +} + +/// The boot stage on `flash`: decodes both copies, picks the slot with +/// `select`, keeps the tried mark of a trial in `mark`, and hands over the +/// started slot with the SVN of the image in that slot. Every slot passes its +/// checks. +fn boot_stage(flash: &RamFlash, mark: &mut Option, images: &[Svn]) -> Handover { + let copy = |at: usize| { + let mut bytes = [0; RECORD_LEN]; + bytes.copy_from_slice(&flash.bytes[at..at + RECORD_LEN]); + Record::decode(&bytes).ok() + }; + let record = newest(copy(COPY_A), copy(COPY_B)).map(|(_, record)| record); + let slots = LAYOUT.slots().iter().map(|slot| slot.id().0); + match select(record, *mark, slots, |_| true) { + Start::Slot { slot, mark: tried } => { + if tried.is_some() { + *mark = tried; + } + started(slot, images[usize::from(slot)]) + } + Start::Recovery => panic!("every slot passes, so the boot stage starts one"), + } +} + +/// Resets the part and lets the boot stage pick the slot. +fn reboot( + session: RecordSession, + mark: &mut Option, + images: &[Svn], +) -> RecordSession { + let flash = session.into_storage(); + let handover = boot_stage(&flash, mark, images); + boot(flash, handover).0 +} + +/// A part that has run slot 0 at the old SVN and holds an intact record. +fn settled_part() -> RecordSession { + let (mut session, _) = boot(RamFlash::erased(), started(0, OLD)); + // The fresh record filled copy A. The writes below fill copy B, then + // copy A again, so both copies decode. + session.prepare(NEW).expect("prepare"); + session.revert().expect("revert"); + session +} + +#[test] +fn a_new_part_writes_a_fresh_record_for_the_started_slot() { + let (session, found) = boot(RamFlash::erased(), started(1, OLD)); + + assert_eq!(found, Found::Rewritten(Rewrite::NoValidCopy)); + assert_eq!(session.state(), Ok(SelfUpdateState::Idle)); + assert_eq!(session.running(), Ok(RunningImage::confirmed(OLD))); + assert_eq!(session.next_trial_slot(), Some(SlotId(0))); + + let (_, found) = boot(session.into_storage(), started(1, OLD)); + assert_eq!(found, Found::OneValidCopy, "one write fills one copy"); +} + +#[test] +fn an_update_runs_its_trial_and_completes_across_resets() { + let mut images = [OLD, OLD]; + let mut mark = None; + let mut session = settled_part(); + assert_eq!(session.next_trial_slot(), Some(SlotId(1))); + session.prepare(NEW).expect("prepare"); + images[1] = NEW; + session.set_trial_pending().expect("mark pending"); + assert_eq!(session.trial_slot(), Some(SlotId(1))); + + let mut session = reboot(session, &mut mark, &images); + let state = session.state().expect("state"); + assert_eq!(state, SelfUpdateState::TrialPending { svn: NEW }); + assert_eq!(session.running(), Ok(RunningImage::trial(NEW))); + assert_eq!( + trial_outcome(state, session.running().expect("running")), + TrialOutcome::InProgress + ); + session.confirm().expect("confirm"); + + assert_eq!( + session.running(), + Ok(RunningImage::trial(NEW)), + "the answer holds for the whole boot" + ); + assert_eq!( + session.trial_slot(), + None, + "the confirm moved the trial slot" + ); + + // A reset before the SVN floor advance. The confirm wrote slot 1 in as + // the confirmed slot, so the boot stage starts slot 1 with no mark. + // Slot 1 holds the image of the session until the complete, so + // `running` reports the trial. + let mut session = reboot(session, &mut mark, &images); + let state = session.state().expect("state"); + assert_eq!(state, SelfUpdateState::Committed { svn: NEW }); + assert_eq!(session.running(), Ok(RunningImage::trial(NEW))); + assert_eq!( + trial_outcome(state, session.running().expect("running")), + TrialOutcome::ConfirmedUncommitted { svn: NEW } + ); + session.complete().expect("complete"); + + let session = reboot(session, &mut mark, &images); + assert_eq!(session.state(), Ok(SelfUpdateState::Idle)); + assert_eq!(session.running(), Ok(RunningImage::confirmed(NEW))); + assert_eq!(session.next_trial_slot(), Some(SlotId(0))); +} + +// The trial boot ends in a reset before the confirm. The tried mark makes +// the boot stage start the confirmed slot, and settlement reverts. +#[test] +fn a_trial_that_fell_back_reads_unconfirmed_and_reverts() { + let mut images = [OLD, OLD]; + let mut mark = None; + let mut session = settled_part(); + session.prepare(NEW).expect("prepare"); + images[1] = NEW; + session.set_trial_pending().expect("mark pending"); + let session = reboot(session, &mut mark, &images); + assert_eq!(session.running(), Ok(RunningImage::trial(NEW))); + + let mut session = reboot(session, &mut mark, &images); + assert_eq!(session.running(), Ok(RunningImage::confirmed(OLD))); + let state = session.state().expect("state"); + assert_eq!( + trial_outcome(state, session.running().expect("running")), + TrialOutcome::Unconfirmed + ); + session.revert().expect("revert"); + assert_eq!(session.state(), Ok(SelfUpdateState::Idle)); + assert_eq!(session.next_trial_slot(), Some(SlotId(1))); +} + +// The revert writes the previous slot from the Committed session back as +// the confirmed slot, so at the next boot the boot stage starts the old +// image. +#[test] +fn a_revert_from_committed_restores_the_previous_slot() { + let mut images = [OLD, OLD]; + let mut mark = None; + let mut session = settled_part(); + session.prepare(NEW).expect("prepare"); + images[1] = NEW; + session.set_trial_pending().expect("mark pending"); + let mut session = reboot(session, &mut mark, &images); + session.confirm().expect("confirm"); + session.revert().expect("revert"); + + let session = reboot(session, &mut mark, &images); + assert_eq!(session.state(), Ok(SelfUpdateState::Idle)); + assert_eq!(session.running(), Ok(RunningImage::confirmed(OLD))); + assert_eq!(session.next_trial_slot(), Some(SlotId(1))); +} + +// After the confirm, slot 1 runs at an SVN other than the session SVN, as +// after a writer with flash access replaced the record. `running` still +// reports the trial, so settlement reverts and reports +// `UnclaimedImageRunning`. At the next reset the boot stage starts slot 0. +#[test] +fn a_committed_session_at_another_svn_reports_the_trial_and_reverts() { + let images = [OLD, NEW]; + let mut mark = None; + let mut session = settled_part(); + session.prepare(NEW).expect("prepare"); + session.set_trial_pending().expect("mark pending"); + let mut session = reset(session, started(1, NEW)); + session.confirm().expect("confirm"); + + let mut session = reset(session, started(1, OLD)); + let running = session.running().expect("running"); + assert_eq!(running, RunningImage::trial(OLD)); + assert_eq!( + trial_outcome(session.state().expect("state"), running), + TrialOutcome::Unconfirmed + ); + session.revert().expect("revert"); + + let session = reboot(session, &mut mark, &images); + assert_eq!(session.running(), Ok(RunningImage::confirmed(OLD))); +} + +// After the confirm, slot 0 holds the image a revert writes back, and slot +// 1 is confirmed and runs. On `LAYOUT` no slot is left for a new update. +#[test] +fn prepare_after_the_confirm_keeps_the_previous_slot() { + let mut session = settled_part(); + session.prepare(NEW).expect("prepare"); + session.set_trial_pending().expect("mark pending"); + let mut session = reset(session, started(1, NEW)); + session.confirm().expect("confirm"); + + assert_eq!(session.next_trial_slot(), None); + assert_eq!(session.prepare(NEW), Err(RecordError::NoFreeSlot)); +} + +#[test] +fn a_repeated_confirm_writes_nothing() { + let mut session = settled_part(); + session.prepare(NEW).expect("prepare"); + session.set_trial_pending().expect("mark pending"); + let mut session = reset(session, started(1, NEW)); + session.confirm().expect("confirm"); + session.storage_mut().writes = 0; + + session.confirm().expect("repeat confirm"); + assert_eq!(session.into_storage().writes, 0); +} + +// The trial had its try and the boot stage started the confirmed slot. A +// confirm in that boot would write slot 1 in as confirmed, and the image in +// slot 1 did not run. +#[test] +fn confirm_is_refused_when_the_trial_slot_does_not_run() { + let mut session = settled_part(); + session.prepare(NEW).expect("prepare"); + session.set_trial_pending().expect("mark pending"); + let mut session = reset(session, started(0, OLD)); + + assert_eq!(session.confirm(), Err(RecordError::TrialNotRunning)); + assert_eq!( + session.state(), + Ok(SelfUpdateState::TrialPending { svn: NEW }) + ); +} + +#[test] +fn a_repeated_transition_writes_nothing() { + let mut session = settled_part(); + session.prepare(NEW).expect("prepare"); + session.set_trial_pending().expect("mark pending"); + let mut flash = session.into_storage(); + flash.writes = 0; + let (mut session, _) = boot(flash, started(0, OLD)); + + session.set_trial_pending().expect("repeat"); + session.revert().expect("revert"); + session.revert().expect("repeat revert"); + session.complete().expect("complete from Idle"); + + assert_eq!( + session.into_storage().writes, + 1, + "only the first revert writes" + ); +} + +#[test] +fn a_transition_from_the_wrong_state_is_refused() { + let mut session = settled_part(); + assert_eq!( + session.set_trial_pending(), + Err(RecordError::WrongState(SelfUpdateState::Idle)) + ); + assert_eq!( + session.confirm(), + Err(RecordError::WrongState(SelfUpdateState::Idle)) + ); + session.prepare(NEW).expect("prepare"); + assert_eq!( + session.complete(), + Err(RecordError::WrongState(SelfUpdateState::Prepared { + svn: NEW + })) + ); +} + +// An unclaimed trial runs from slot 1 while slot 0 stays confirmed. In +// `LAYOUT`, slot 0 is confirmed and slot 1 runs, so `prepare` has no slot to +// write the image into. +#[test] +fn prepare_refuses_to_overwrite_the_running_slot() { + let mut session = settled_part(); + session.prepare(NEW).expect("prepare"); + session.set_trial_pending().expect("mark pending"); + let mut session = reset(session, started(1, NEW)); + session.revert().expect("revert"); + assert_eq!(session.running(), Ok(RunningImage::trial(NEW))); + + assert_eq!(session.next_trial_slot(), None); + assert_eq!(session.prepare(NEW), Err(RecordError::NoFreeSlot)); +} + +// The confirmed slot failed its checks while the session read Prepared, and +// the walk started the trial slot. The eRoT writes the trial slot in as +// confirmed, so the next update finds a free slot without another reset. +#[test] +fn a_walk_to_a_prepared_trial_slot_rewrites_the_record() { + let mut session = settled_part(); + session.prepare(NEW).expect("prepare"); + let flash = session.into_storage().power_cycle(); + + let (session, found) = boot(flash, started(1, NEW)); + assert_eq!(found, Found::Rewritten(Rewrite::Walked)); + assert_eq!(session.state(), Ok(SelfUpdateState::Idle)); + assert_eq!(session.running(), Ok(RunningImage::confirmed(NEW))); + assert_eq!(session.next_trial_slot(), Some(SlotId(0))); +} + +// The slots the record names failed their checks and the boot stage walked +// to slot 2. The eRoT writes slot 2 in as confirmed and drops the session. +#[test] +fn a_walk_to_another_slot_rewrites_the_record() { + let (mut session, _) = + RecordSession::open(RamFlash::erased(), COPIES, LAYOUT_THREE, started(0, OLD)) + .expect("the record opens"); + session.prepare(NEW).expect("prepare"); + session.set_trial_pending().expect("mark pending"); + let flash = session.into_storage().power_cycle(); + + let (session, found) = RecordSession::open(flash, COPIES, LAYOUT_THREE, started(2, OLD)) + .expect("the record opens"); + assert_eq!(found, Found::Rewritten(Rewrite::Walked)); + assert_eq!(session.state(), Ok(SelfUpdateState::Idle)); + assert_eq!(session.running(), Ok(RunningImage::confirmed(OLD))); + assert_eq!(session.next_trial_slot(), Some(SlotId(0))); +} + +// A record written for `LAYOUT_THREE` names slot 2, which `LAYOUT` does not +// have. +#[test] +fn a_record_naming_an_unknown_slot_is_rewritten() { + let (session, _) = + RecordSession::open(RamFlash::erased(), COPIES, LAYOUT_THREE, started(2, OLD)) + .expect("the record opens"); + let (session, found) = boot(session.into_storage(), started(0, OLD)); + + assert_eq!(found, Found::Rewritten(Rewrite::UnknownSlot)); + assert_eq!(session.state(), Ok(SelfUpdateState::Idle)); +} + +#[test] +fn a_handover_naming_an_unknown_slot_is_refused() { + let opened = RecordSession::open( + RamFlash::erased(), + COPIES, + LAYOUT, + started(UNKNOWN_SLOT, OLD), + ); + assert!(matches!( + opened, + Err(RecordError::UnknownStartedSlot(SlotId(UNKNOWN_SLOT))) + )); +} + +// A refused write changes neither the flash nor the record in RAM, so the +// retry writes the same copy. +#[test] +fn a_failed_write_keeps_the_record_and_the_retry_succeeds() { + let mut session = settled_part(); + session.storage_mut().refuse_next = true; + + assert_eq!( + session.prepare(NEW), + Err(RecordError::Storage(FlashError::Refused)) + ); + assert_eq!(session.state(), Ok(SelfUpdateState::Idle)); + + session.prepare(NEW).expect("retry"); + let (session, found) = boot(session.into_storage(), started(0, OLD)); + assert_eq!(found, Found::Intact); + assert_eq!(session.state(), Ok(SelfUpdateState::Prepared { svn: NEW })); +} + +/// One transition of a full update, from the state before it. +type Step = fn(&mut RecordSession) -> Result<(), RecordError>; + +// Power goes away during each transition, at every byte of the write. After +// the reset the state is the one before the transition, or the one after it +// when the flash holds the whole copy. +#[test] +fn a_torn_write_leaves_the_state_before_or_after() { + // The update path, and the boot each step runs on. + let path: [(Step, Handover); 4] = [ + (|s| s.prepare(NEW), started(0, OLD)), + (|s| s.set_trial_pending(), started(0, OLD)), + (|s| s.confirm(), started(1, NEW)), + (|s| s.complete(), started(1, NEW)), + ]; + // Each step under test, with how many steps of the path run before it. + // The revert runs from Committed, the last state that holds a session. + let revert: (Step, Handover) = (|s| s.revert(), started(1, NEW)); + // The third value is the boot the boot stage starts after the step + // succeeds: slot 1 from the pending trial on, first as the trial slot and + // after the confirm as the confirmed slot, and slot 0 after the revert, + // which writes slot 0 back as the confirmed slot. + let cases = [ + (path[0], 0, started(0, OLD)), + (path[1], 1, started(1, NEW)), + (path[2], 2, started(1, NEW)), + (path[3], 3, started(1, NEW)), + (revert, 3, started(0, OLD)), + ]; + for (index, &((step, handover), earlier_steps, next_boot)) in cases.iter().enumerate() { + for cut in 0..=RECORD_LEN { + let mut session = settled_part(); + for &(earlier, earlier_boot) in &path[..earlier_steps] { + session = reset(session, earlier_boot); + earlier(&mut session).expect("an earlier step"); + } + let mut session = reset(session, handover); + let before = session.state().expect("state"); + let mut after = reset_copy(&session, handover); + step(&mut after).expect("the step without a cut"); + let after = after.state().expect("state"); + + session.storage_mut().cut_next = Some(cut); + assert!(step(&mut session).is_err(), "step {index}, cut {cut}"); + let (mut session, _) = boot(session.into_storage(), handover); + let state = session.state().expect("state"); + if cut < RECORD_LEN { + assert_eq!(state, before, "step {index}, cut {cut}"); + // The retry lands on the torn copy and repairs it. + step(&mut session).expect("the retry"); + let (session, found) = boot(session.into_storage(), next_boot); + assert_eq!(found, Found::Intact, "step {index}, cut {cut}"); + assert_eq!(session.state(), Ok(after), "step {index}, cut {cut}"); + } else { + assert_eq!(state, after, "step {index}, whole copy"); + } + } + } +} + +/// A second session on a copy of the flash under `session`, to see what a +/// step does without the cut. +fn reset_copy(session: &RecordSession, handover: Handover) -> RecordSession { + let mut flash = RamFlash::erased(); + flash.bytes = session.storage().bytes; + boot(flash, handover).0 +} + +// After a revert in the trial boot, the record holds no session and the +// trial slot still runs. `running` keeps reporting the trial, so +// `trial_outcome` reads the `Idle` session with a running trial as +// unconfirmed. +#[test] +fn running_reports_the_trial_for_the_whole_trial_boot() { + let mut session = settled_part(); + session.prepare(NEW).expect("prepare"); + session.set_trial_pending().expect("mark pending"); + let mut session = reset(session, started(1, NEW)); + assert_eq!(session.running(), Ok(RunningImage::trial(NEW))); + + session.revert().expect("revert"); + let running = session.running().expect("running"); + assert_eq!(running.selected, BootSelection::Trial); + assert_eq!( + trial_outcome(session.state().expect("state"), running), + TrialOutcome::Unconfirmed + ); +} + +// After the confirm, the signature check or the SVN floor check rejected +// slot 1, and the walk started the previous slot. The eRoT writes slot 0 in as confirmed and drops the +// session, so settlement sees no session and the SVN floor keeps the SVN it +// has. +#[test] +fn a_walk_to_the_previous_slot_rewrites_the_record() { + let mut session = settled_part(); + session.prepare(NEW).expect("prepare"); + session.set_trial_pending().expect("mark pending"); + let mut session = reset(session, started(1, NEW)); + session.confirm().expect("confirm"); + + let (session, found) = boot(session.into_storage(), started(0, OLD)); + assert_eq!(found, Found::Rewritten(Rewrite::Walked)); + assert_eq!(session.state(), Ok(SelfUpdateState::Idle)); + assert_eq!(session.running(), Ok(RunningImage::confirmed(OLD))); + assert_eq!(session.next_trial_slot(), Some(SlotId(1))); +} diff --git a/services/orchestrator/capabilities/src/self_update.rs b/services/orchestrator/capabilities/src/self_update.rs index e7906f30d..e13262a73 100644 --- a/services/orchestrator/capabilities/src/self_update.rs +++ b/services/orchestrator/capabilities/src/self_update.rs @@ -224,11 +224,13 @@ pub trait SelfUpdate { /// Which image this boot is running, and at which SVN. /// - /// [`Confirmed`](BootSelection::Confirmed) whenever no trial is in - /// flight, an `Idle` session included: with nothing pending there is - /// nothing else to be running. The SVN is what the boot stage read - /// from the signed header of the image it started, handed over at boot; - /// `None` when the platform has no such handover. + /// [`Trial`](BootSelection::Trial) when the boot stage started the image + /// of a session in flight, [`Confirmed`](BootSelection::Confirmed) for + /// any other image. The answer holds for the whole boot: a confirm, a + /// revert or a complete during the boot changes the session, not the + /// running image. The SVN is what the boot stage read from the signed + /// header of the image it started, handed over at boot; `None` when the + /// platform has no such handover. /// /// Read together with [`state`](Self::state) once at boot, before /// settlement writes the session, as one snapshot. The boot stage reports