From 9f229ac7508187b1c6754984f0b33719e5f8167f Mon Sep 17 00:00:00 2001 From: Steven Schulteis Date: Sun, 16 Nov 2025 09:50:32 -0600 Subject: Add missing feature documentation for embassy-boot --- embassy-boot/Cargo.toml | 14 +++++++++++++- embassy-boot/src/lib.rs | 4 ++++ 2 files changed, 17 insertions(+), 1 deletion(-) diff --git a/embassy-boot/Cargo.toml b/embassy-boot/Cargo.toml index 8c5c1f633..754c6e5f1 100644 --- a/embassy-boot/Cargo.toml +++ b/embassy-boot/Cargo.toml @@ -26,6 +26,7 @@ features = ["defmt"] [dependencies] defmt = { version = "1.0.1", optional = true } digest = "0.10" +document-features = "0.2.7" log = { version = "0.4", optional = true } ed25519-dalek = { version = "2", default-features = false, features = ["digest"], optional = true } embassy-embedded-hal = { version = "0.5.0", path = "../embassy-embedded-hal" } @@ -45,11 +46,22 @@ critical-section = { version = "1.1.1", features = ["std"] } ed25519-dalek = { version = "2", default-features = false, features = ["std", "rand_core", "digest"] } [features] +## Use [`defmt`](https://docs.rs/defmt/latest/defmt/) for logging defmt = ["dep:defmt"] +## Use log for logging log = ["dep:log"] + +## Enable for devices that set erased flash bytes to `0x00` instead of the usual `0xFF` +flash-erase-zero = [] + +#! ## Firmware Signing +#! Enable one of these features to allow verification of DFU signatures with +#! `FirmwareUpdater::verify_and_mark_updated`. + +## Use the `ed25519-dalek` package to verify DFU signatures. ed25519-dalek = ["dep:ed25519-dalek", "_verify"] +## Use the `salty` package to verify DFU signatures. ed25519-salty = ["dep:salty", "_verify"] -flash-erase-zero = [] #Internal features _verify = [] diff --git a/embassy-boot/src/lib.rs b/embassy-boot/src/lib.rs index 7dc811f66..3e61d6036 100644 --- a/embassy-boot/src/lib.rs +++ b/embassy-boot/src/lib.rs @@ -3,6 +3,10 @@ #![allow(unsafe_op_in_unsafe_fn)] #![warn(missing_docs)] #![doc = include_str!("../README.md")] + +//! ## Feature flags +#![doc = document_features::document_features!(feature_label = r#"{feature}"#)] + mod fmt; mod boot_loader; -- cgit From 5e90c3fdb3b87970926b1ecc86cc4ad8ab260569 Mon Sep 17 00:00:00 2001 From: Steven Schulteis Date: Sun, 16 Nov 2025 09:51:38 -0600 Subject: Fix docs for embassy-boot state partition size --- docs/pages/bootloader.adoc | 6 +++--- embassy-boot/src/boot_loader.rs | 12 +++++++----- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/pages/bootloader.adoc b/docs/pages/bootloader.adoc index b0f0331aa..c010b0622 100644 --- a/docs/pages/bootloader.adoc +++ b/docs/pages/bootloader.adoc @@ -43,14 +43,14 @@ Partition Size~dfu~= Partition Size~active~+ Page Size~active~ + All values are specified in bytes. -* BOOTLOADER STATE - Where the bootloader stores the current state describing if the active and dfu partitions need to be swapped. When the new firmware has been written to the DFU partition, a magic field is written to instruct the bootloader that the partitions should be swapped. This partition must be able to store a magic field as well as the partition swap progress. The partition size given by: +* BOOTLOADER STATE - Where the bootloader stores the current state describing if the active and dfu partitions need to be swapped. When the new firmware has been written to the DFU partition, a magic field is written to instruct the bootloader that the partitions should be swapped. This partition must be able to store a magic field as well as the partition swap progress. The partition size is given by: + -Partition Size~state~ = Write Size~state~ + (2 × Partition Size~active~ / Page Size~active~) +Partition Size~state~ = (2 × Write Size~state~) + (4 × Write Size~state~ × Partition Size~active~ / Page Size~active~) + All values are specified in bytes. The partitions for ACTIVE (+BOOTLOADER), DFU and BOOTLOADER_STATE may be placed in separate flash. The page size used by the bootloader is determined by the lowest common multiple of the ACTIVE and DFU page sizes. -The BOOTLOADER_STATE partition must be big enough to store one word per page in the ACTIVE and DFU partitions combined. +The BOOTLOADER_STATE partition must be big enough to store two words, plus four words per page in the ACTIVE partition. The bootloader has a platform-agnostic part, which implements the power fail safe swapping algorithm given the boundaries set by the partitions. The platform-specific part is a minimal shim that provides additional functionality such as watchdogs or supporting the nRF52 softdevice. diff --git a/embassy-boot/src/boot_loader.rs b/embassy-boot/src/boot_loader.rs index c38940d6e..a3a307051 100644 --- a/embassy-boot/src/boot_loader.rs +++ b/embassy-boot/src/boot_loader.rs @@ -135,10 +135,12 @@ pub struct BootLoader { dfu: DFU, /// The state partition has the following format: /// All ranges are in multiples of WRITE_SIZE bytes. - /// | Range | Description | - /// | 0..1 | Magic indicating bootloader state. BOOT_MAGIC means boot, SWAP_MAGIC means swap. | - /// | 1..2 | Progress validity. ERASE_VALUE means valid, !ERASE_VALUE means invalid. | - /// | 2..2 + N | Progress index used while swapping or reverting + /// N = Active partition size divided by WRITE_SIZE. + /// | Range | Description | + /// | 0..1 | Magic indicating bootloader state. BOOT_MAGIC means boot, SWAP_MAGIC means swap. | + /// | 1..2 | Progress validity. ERASE_VALUE means valid, !ERASE_VALUE means invalid. | + /// | 2..(2 + 2N) | Progress index used while swapping | + /// | (2 + 2N)..(2 + 4N) | Progress index used while reverting state: STATE, } @@ -429,7 +431,7 @@ fn assert_partitions( assert_eq!(dfu.capacity() as u32 % page_size, 0); // DFU partition has to be bigger than ACTIVE partition to handle swap algorithm assert!(dfu.capacity() as u32 - active.capacity() as u32 >= page_size); - assert!(2 + 2 * (active.capacity() as u32 / page_size) <= state.capacity() as u32 / STATE::WRITE_SIZE as u32); + assert!(2 + 4 * (active.capacity() as u32 / page_size) <= state.capacity() as u32 / STATE::WRITE_SIZE as u32); } #[cfg(test)] -- cgit From 579f1b4e0b10671605d63d5ddc67a4d9384e84b9 Mon Sep 17 00:00:00 2001 From: Steven Schulteis Date: Tue, 18 Nov 2025 19:46:07 -0600 Subject: Update changelog --- embassy-boot/CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/embassy-boot/CHANGELOG.md b/embassy-boot/CHANGELOG.md index 8d6395357..1d41043cb 100644 --- a/embassy-boot/CHANGELOG.md +++ b/embassy-boot/CHANGELOG.md @@ -8,6 +8,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## Unreleased - ReleaseDate +- Fixed documentation and assertion of STATE partition size requirements +- Added documentation for package features + ## 0.6.1 - 2025-08-26 - First release with changelog. -- cgit