Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 51 additions & 0 deletions services/orchestrator/adapters/record/BUILD.bazel
Original file line number Diff line number Diff line change
@@ -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",
)
48 changes: 48 additions & 0 deletions services/orchestrator/adapters/record/format/crc32.rs
Original file line number Diff line number Diff line change
@@ -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);
}
}
31 changes: 31 additions & 0 deletions services/orchestrator/adapters/record/format/lib.rs
Original file line number Diff line number Diff line change
@@ -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};
106 changes: 106 additions & 0 deletions services/orchestrator/adapters/record/format/mark.rs
Original file line number Diff line number Diff line change
@@ -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::<u32>() == 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<Self> {
if bytes[MAGIC_AT..COUNTER_AT] != MARK_MAGIC {
return None;
}
let word = |at: usize| {
let mut word = [0; size_of::<u32>()];
word.copy_from_slice(&bytes[at..at + size_of::<u32>()]);
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");
}
}
}
Loading