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