embassy_boot/firmware_updater/
blocking.rs

1use digest::Digest;
2#[cfg(target_os = "none")]
3use embassy_embedded_hal::flash::partition::BlockingPartition;
4#[cfg(target_os = "none")]
5use embassy_sync::blocking_mutex::raw::NoopRawMutex;
6use embedded_storage::nor_flash::NorFlash;
7
8use super::FirmwareUpdaterConfig;
9use crate::{FirmwareUpdaterError, State, BOOT_MAGIC, DFU_DETACH_MAGIC, STATE_ERASE_VALUE, SWAP_MAGIC};
10
11/// Blocking FirmwareUpdater is an application API for interacting with the BootLoader without the ability to
12/// 'mess up' the internal bootloader state
13pub struct BlockingFirmwareUpdater<'d, DFU: NorFlash, STATE: NorFlash> {
14    dfu: DFU,
15    state: BlockingFirmwareState<'d, STATE>,
16    last_erased_dfu_sector_index: Option<usize>,
17}
18
19#[cfg(target_os = "none")]
20impl<'a, DFU: NorFlash, STATE: NorFlash>
21    FirmwareUpdaterConfig<BlockingPartition<'a, NoopRawMutex, DFU>, BlockingPartition<'a, NoopRawMutex, STATE>>
22{
23    /// Constructs a `FirmwareUpdaterConfig` instance from flash memory and address symbols defined in the linker file.
24    ///
25    /// This method initializes `BlockingPartition` instances for the DFU (Device Firmware Update), and state
26    /// partitions, leveraging start and end addresses specified by the linker. These partitions are critical
27    /// for managing firmware updates, application state, and boot operations within the bootloader.
28    ///
29    /// # Parameters
30    /// - `dfu_flash`: A reference to a mutex-protected `RefCell` for the DFU partition's flash interface.
31    /// - `state_flash`: A reference to a mutex-protected `RefCell` for the state partition's flash interface.
32    ///
33    /// # Safety
34    /// The method contains `unsafe` blocks for dereferencing raw pointers that represent the start and end addresses
35    /// of the bootloader's partitions in flash memory. It is crucial that these addresses are accurately defined
36    /// in the memory.x file to prevent undefined behavior.
37    ///
38    /// The caller must ensure that the memory regions defined by these symbols are valid and that the flash memory
39    /// interfaces provided are compatible with these regions.
40    ///
41    /// # Returns
42    /// A `FirmwareUpdaterConfig` instance with `BlockingPartition` instances for the DFU, and state partitions.
43    ///
44    /// # Example
45    /// ```ignore
46    /// // Assume `dfu_flash`, and `state_flash` share the same flash memory interface.
47    /// let layout = Flash::new_blocking(p.FLASH).into_blocking_regions();
48    /// let flash = Mutex::new(RefCell::new(layout.bank1_region));
49    ///
50    /// let config = FirmwareUpdaterConfig::from_linkerfile_blocking(&flash, &flash);
51    /// // `config` can now be used to create a `FirmwareUpdater` instance for managing boot operations.
52    /// ```
53    /// Working examples can be found in the bootloader examples folder.
54    pub fn from_linkerfile_blocking(
55        dfu_flash: &'a embassy_sync::blocking_mutex::Mutex<NoopRawMutex, core::cell::RefCell<DFU>>,
56        state_flash: &'a embassy_sync::blocking_mutex::Mutex<NoopRawMutex, core::cell::RefCell<STATE>>,
57    ) -> Self {
58        extern "C" {
59            static __bootloader_state_start: u32;
60            static __bootloader_state_end: u32;
61            static __bootloader_dfu_start: u32;
62            static __bootloader_dfu_end: u32;
63        }
64
65        let dfu = unsafe {
66            let start = &__bootloader_dfu_start as *const u32 as u32;
67            let end = &__bootloader_dfu_end as *const u32 as u32;
68            trace!("DFU: 0x{:x} - 0x{:x}", start, end);
69
70            BlockingPartition::new(dfu_flash, start, end - start)
71        };
72        let state = unsafe {
73            let start = &__bootloader_state_start as *const u32 as u32;
74            let end = &__bootloader_state_end as *const u32 as u32;
75            trace!("STATE: 0x{:x} - 0x{:x}", start, end);
76
77            BlockingPartition::new(state_flash, start, end - start)
78        };
79
80        Self { dfu, state }
81    }
82}
83
84impl<'d, DFU: NorFlash, STATE: NorFlash> BlockingFirmwareUpdater<'d, DFU, STATE> {
85    /// Create a firmware updater instance with partition ranges for the update and state partitions.
86    ///
87    /// # Safety
88    ///
89    /// The `aligned` buffer must have a size of STATE::WRITE_SIZE, and follow the alignment rules for the flash being read from
90    /// and written to.
91    pub fn new(config: FirmwareUpdaterConfig<DFU, STATE>, aligned: &'d mut [u8]) -> Self {
92        Self {
93            dfu: config.dfu,
94            state: BlockingFirmwareState::new(config.state, aligned),
95            last_erased_dfu_sector_index: None,
96        }
97    }
98
99    /// Obtain the current state.
100    ///
101    /// This is useful to check if the bootloader has just done a swap, in order
102    /// to do verifications and self-tests of the new image before calling
103    /// `mark_booted`.
104    pub fn get_state(&mut self) -> Result<State, FirmwareUpdaterError> {
105        self.state.get_state()
106    }
107
108    /// Verify the DFU given a public key. If there is an error then DO NOT
109    /// proceed with updating the firmware as it must be signed with a
110    /// corresponding private key (otherwise it could be malicious firmware).
111    ///
112    /// Mark to trigger firmware swap on next boot if verify succeeds.
113    ///
114    /// If the "ed25519-salty" feature is set (or another similar feature) then the signature is expected to have
115    /// been generated from a SHA-512 digest of the firmware bytes.
116    ///
117    /// If no signature feature is set then this method will always return a
118    /// signature error.
119    #[cfg(feature = "_verify")]
120    pub fn verify_and_mark_updated(
121        &mut self,
122        _public_key: &[u8; 32],
123        _signature: &[u8; 64],
124        _update_len: u32,
125    ) -> Result<(), FirmwareUpdaterError> {
126        assert!(_update_len <= self.dfu.capacity() as u32);
127
128        self.state.verify_booted()?;
129
130        #[cfg(feature = "ed25519-dalek")]
131        {
132            use ed25519_dalek::{Signature, SignatureError, Verifier, VerifyingKey};
133
134            use crate::digest_adapters::ed25519_dalek::Sha512;
135
136            let into_signature_error = |e: SignatureError| FirmwareUpdaterError::Signature(e.into());
137
138            let public_key = VerifyingKey::from_bytes(_public_key).map_err(into_signature_error)?;
139            let signature = Signature::from_bytes(_signature);
140
141            let mut message = [0; 64];
142            let mut chunk_buf = [0; 2];
143            self.hash::<Sha512>(_update_len, &mut chunk_buf, &mut message)?;
144
145            public_key.verify(&message, &signature).map_err(into_signature_error)?;
146            return self.state.mark_updated();
147        }
148        #[cfg(feature = "ed25519-salty")]
149        {
150            use salty::{PublicKey, Signature};
151
152            use crate::digest_adapters::salty::Sha512;
153
154            fn into_signature_error<E>(_: E) -> FirmwareUpdaterError {
155                FirmwareUpdaterError::Signature(signature::Error::default())
156            }
157
158            let public_key = PublicKey::try_from(_public_key).map_err(into_signature_error)?;
159            let signature = Signature::try_from(_signature).map_err(into_signature_error)?;
160
161            let mut message = [0; 64];
162            let mut chunk_buf = [0; 2];
163            self.hash::<Sha512>(_update_len, &mut chunk_buf, &mut message)?;
164
165            let r = public_key.verify(&message, &signature);
166            trace!(
167                "Verifying with public key {}, signature {} and message {} yields ok: {}",
168                public_key.to_bytes(),
169                signature.to_bytes(),
170                message,
171                r.is_ok()
172            );
173            r.map_err(into_signature_error)?;
174            return self.state.mark_updated();
175        }
176        #[cfg(not(any(feature = "ed25519-dalek", feature = "ed25519-salty")))]
177        {
178            Err(FirmwareUpdaterError::Signature(signature::Error::new()))
179        }
180    }
181
182    /// Verify the update in DFU with any digest.
183    pub fn hash<D: Digest>(
184        &mut self,
185        update_len: u32,
186        chunk_buf: &mut [u8],
187        output: &mut [u8],
188    ) -> Result<(), FirmwareUpdaterError> {
189        let mut digest = D::new();
190        for offset in (0..update_len).step_by(chunk_buf.len()) {
191            self.dfu.read(offset, chunk_buf)?;
192            let len = core::cmp::min((update_len - offset) as usize, chunk_buf.len());
193            digest.update(&chunk_buf[..len]);
194        }
195        output.copy_from_slice(digest.finalize().as_slice());
196        Ok(())
197    }
198
199    /// Read a slice of data from the DFU storage peripheral, starting the read
200    /// operation at the given address offset, and reading `buf.len()` bytes.
201    ///
202    /// # Errors
203    ///
204    /// Returns an error if the arguments are not aligned or out of bounds.
205    pub fn read_dfu(&mut self, offset: u32, buf: &mut [u8]) -> Result<(), FirmwareUpdaterError> {
206        self.dfu.read(offset, buf)?;
207        Ok(())
208    }
209
210    /// Mark to trigger firmware swap on next boot.
211    #[cfg(not(feature = "_verify"))]
212    pub fn mark_updated(&mut self) -> Result<(), FirmwareUpdaterError> {
213        self.state.mark_updated()
214    }
215
216    /// Mark to trigger USB DFU device on next boot.
217    pub fn mark_dfu(&mut self) -> Result<(), FirmwareUpdaterError> {
218        self.state.verify_booted()?;
219        self.state.mark_dfu()
220    }
221
222    /// Mark firmware boot successful and stop rollback on reset.
223    pub fn mark_booted(&mut self) -> Result<(), FirmwareUpdaterError> {
224        self.state.mark_booted()
225    }
226
227    /// Writes firmware data to the device.
228    ///
229    /// This function writes the given data to the firmware area starting at the specified offset.
230    /// It handles sector erasures and data writes while verifying the device is in a proper state
231    /// for firmware updates. The function ensures that only unerased sectors are erased before
232    /// writing and efficiently handles the writing process across sector boundaries and in
233    /// various configurations (data size, sector size, etc.).
234    ///
235    /// # Arguments
236    ///
237    /// * `offset` - The starting offset within the firmware area where data writing should begin.
238    /// * `data` - A slice of bytes representing the firmware data to be written. It must be a
239    /// multiple of NorFlash WRITE_SIZE.
240    ///
241    /// # Returns
242    ///
243    /// A `Result<(), FirmwareUpdaterError>` indicating the success or failure of the write operation.
244    ///
245    /// # Errors
246    ///
247    /// This function will return an error if:
248    ///
249    /// - The device is not in a proper state to receive firmware updates (e.g., not booted).
250    /// - There is a failure erasing a sector before writing.
251    /// - There is a failure writing data to the device.
252    pub fn write_firmware(&mut self, offset: usize, data: &[u8]) -> Result<(), FirmwareUpdaterError> {
253        // Make sure we are running a booted firmware to avoid reverting to a bad state.
254        self.state.verify_booted()?;
255
256        // Initialize variables to keep track of the remaining data and the current offset.
257        let mut remaining_data = data;
258        let mut offset = offset;
259
260        // Continue writing as long as there is data left to write.
261        while !remaining_data.is_empty() {
262            // Compute the current sector and its boundaries.
263            let current_sector = offset / DFU::ERASE_SIZE;
264            let sector_start = current_sector * DFU::ERASE_SIZE;
265            let sector_end = sector_start + DFU::ERASE_SIZE;
266            // Determine if the current sector needs to be erased before writing.
267            let need_erase = self
268                .last_erased_dfu_sector_index
269                .map_or(true, |last_erased_sector| current_sector != last_erased_sector);
270
271            // If the sector needs to be erased, erase it and update the last erased sector index.
272            if need_erase {
273                self.dfu.erase(sector_start as u32, sector_end as u32)?;
274                self.last_erased_dfu_sector_index = Some(current_sector);
275            }
276
277            // Calculate the size of the data chunk that can be written in the current iteration.
278            let write_size = core::cmp::min(remaining_data.len(), sector_end - offset);
279            // Split the data to get the current chunk to be written and the remaining data.
280            let (data_chunk, rest) = remaining_data.split_at(write_size);
281
282            // Write the current data chunk.
283            self.dfu.write(offset as u32, data_chunk)?;
284
285            // Update the offset and remaining data for the next iteration.
286            remaining_data = rest;
287            offset += write_size;
288        }
289
290        Ok(())
291    }
292
293    /// Prepare for an incoming DFU update by erasing the entire DFU area and
294    /// returning its `Partition`.
295    ///
296    /// Using this instead of `write_firmware` allows for an optimized API in
297    /// exchange for added complexity.
298    pub fn prepare_update(&mut self) -> Result<&mut DFU, FirmwareUpdaterError> {
299        self.state.verify_booted()?;
300        self.dfu.erase(0, self.dfu.capacity() as u32)?;
301
302        Ok(&mut self.dfu)
303    }
304}
305
306/// Manages the state partition of the firmware update.
307///
308/// Can be used standalone for more fine grained control, or as part of the updater.
309pub struct BlockingFirmwareState<'d, STATE> {
310    state: STATE,
311    aligned: &'d mut [u8],
312}
313
314impl<'d, STATE: NorFlash> BlockingFirmwareState<'d, STATE> {
315    /// Creates a firmware state instance from a FirmwareUpdaterConfig, with a buffer for magic content and state partition.
316    ///
317    /// # Safety
318    ///
319    /// The `aligned` buffer must have a size of STATE::WRITE_SIZE, and follow the alignment rules for the flash being read from
320    /// and written to.
321    pub fn from_config<DFU: NorFlash>(config: FirmwareUpdaterConfig<DFU, STATE>, aligned: &'d mut [u8]) -> Self {
322        Self::new(config.state, aligned)
323    }
324
325    /// Create a firmware state instance with a buffer for magic content and state partition.
326    ///
327    /// # Safety
328    ///
329    /// The `aligned` buffer must have a size of STATE::WRITE_SIZE, and follow the alignment rules for the flash being read from
330    /// and written to.
331    pub fn new(state: STATE, aligned: &'d mut [u8]) -> Self {
332        assert_eq!(aligned.len(), STATE::WRITE_SIZE);
333        Self { state, aligned }
334    }
335
336    // Make sure we are running a booted firmware to avoid reverting to a bad state.
337    fn verify_booted(&mut self) -> Result<(), FirmwareUpdaterError> {
338        let state = self.get_state()?;
339        if state == State::Boot || state == State::DfuDetach || state == State::Revert {
340            Ok(())
341        } else {
342            Err(FirmwareUpdaterError::BadState)
343        }
344    }
345
346    /// Obtain the current state.
347    ///
348    /// This is useful to check if the bootloader has just done a swap, in order
349    /// to do verifications and self-tests of the new image before calling
350    /// `mark_booted`.
351    pub fn get_state(&mut self) -> Result<State, FirmwareUpdaterError> {
352        self.state.read(0, &mut self.aligned)?;
353        Ok(State::from(&self.aligned))
354    }
355
356    /// Mark to trigger firmware swap on next boot.
357    pub fn mark_updated(&mut self) -> Result<(), FirmwareUpdaterError> {
358        self.set_magic(SWAP_MAGIC)
359    }
360
361    /// Mark to trigger USB DFU on next boot.
362    pub fn mark_dfu(&mut self) -> Result<(), FirmwareUpdaterError> {
363        self.set_magic(DFU_DETACH_MAGIC)
364    }
365
366    /// Mark firmware boot successful and stop rollback on reset.
367    pub fn mark_booted(&mut self) -> Result<(), FirmwareUpdaterError> {
368        self.set_magic(BOOT_MAGIC)
369    }
370
371    fn set_magic(&mut self, magic: u8) -> Result<(), FirmwareUpdaterError> {
372        self.state.read(0, &mut self.aligned)?;
373
374        if self.aligned.iter().any(|&b| b != magic) {
375            // Read progress validity
376            self.state.read(STATE::WRITE_SIZE as u32, &mut self.aligned)?;
377
378            if self.aligned.iter().any(|&b| b != STATE_ERASE_VALUE) {
379                // The current progress validity marker is invalid
380            } else {
381                // Invalidate progress
382                self.aligned.fill(!STATE_ERASE_VALUE);
383                self.state.write(STATE::WRITE_SIZE as u32, &self.aligned)?;
384            }
385
386            // Clear magic and progress
387            self.state.erase(0, self.state.capacity() as u32)?;
388
389            // Set magic
390            self.aligned.fill(magic);
391            self.state.write(0, &self.aligned)?;
392        }
393        Ok(())
394    }
395}
396
397#[cfg(test)]
398mod tests {
399    use core::cell::RefCell;
400
401    use embassy_embedded_hal::flash::partition::BlockingPartition;
402    use embassy_sync::blocking_mutex::raw::NoopRawMutex;
403    use embassy_sync::blocking_mutex::Mutex;
404    use sha1::{Digest, Sha1};
405
406    use super::*;
407    use crate::mem_flash::MemFlash;
408
409    #[test]
410    fn can_verify_sha1() {
411        let flash = Mutex::<NoopRawMutex, _>::new(RefCell::new(MemFlash::<131072, 4096, 8>::default()));
412        let state = BlockingPartition::new(&flash, 0, 4096);
413        let dfu = BlockingPartition::new(&flash, 65536, 65536);
414        let mut aligned = [0; 8];
415
416        let update = [0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66];
417        let mut to_write = [0; 4096];
418        to_write[..7].copy_from_slice(update.as_slice());
419
420        let mut updater = BlockingFirmwareUpdater::new(FirmwareUpdaterConfig { dfu, state }, &mut aligned);
421        updater.write_firmware(0, to_write.as_slice()).unwrap();
422        let mut chunk_buf = [0; 2];
423        let mut hash = [0; 20];
424        updater
425            .hash::<Sha1>(update.len() as u32, &mut chunk_buf, &mut hash)
426            .unwrap();
427
428        assert_eq!(Sha1::digest(update).as_slice(), hash);
429    }
430
431    #[test]
432    fn can_verify_sha1_sector_bigger_than_chunk() {
433        let flash = Mutex::<NoopRawMutex, _>::new(RefCell::new(MemFlash::<131072, 4096, 8>::default()));
434        let state = BlockingPartition::new(&flash, 0, 4096);
435        let dfu = BlockingPartition::new(&flash, 65536, 65536);
436        let mut aligned = [0; 8];
437
438        let update = [0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66];
439        let mut to_write = [0; 4096];
440        to_write[..7].copy_from_slice(update.as_slice());
441
442        let mut updater = BlockingFirmwareUpdater::new(FirmwareUpdaterConfig { dfu, state }, &mut aligned);
443        let mut offset = 0;
444        for chunk in to_write.chunks(1024) {
445            updater.write_firmware(offset, chunk).unwrap();
446            offset += chunk.len();
447        }
448        let mut chunk_buf = [0; 2];
449        let mut hash = [0; 20];
450        updater
451            .hash::<Sha1>(update.len() as u32, &mut chunk_buf, &mut hash)
452            .unwrap();
453
454        assert_eq!(Sha1::digest(update).as_slice(), hash);
455    }
456
457    #[test]
458    fn can_verify_sha1_sector_smaller_than_chunk() {
459        let flash = Mutex::<NoopRawMutex, _>::new(RefCell::new(MemFlash::<131072, 1024, 8>::default()));
460        let state = BlockingPartition::new(&flash, 0, 4096);
461        let dfu = BlockingPartition::new(&flash, 65536, 65536);
462        let mut aligned = [0; 8];
463
464        let update = [0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66];
465        let mut to_write = [0; 4096];
466        to_write[..7].copy_from_slice(update.as_slice());
467
468        let mut updater = BlockingFirmwareUpdater::new(FirmwareUpdaterConfig { dfu, state }, &mut aligned);
469        let mut offset = 0;
470        for chunk in to_write.chunks(2048) {
471            updater.write_firmware(offset, chunk).unwrap();
472            offset += chunk.len();
473        }
474        let mut chunk_buf = [0; 2];
475        let mut hash = [0; 20];
476        updater
477            .hash::<Sha1>(update.len() as u32, &mut chunk_buf, &mut hash)
478            .unwrap();
479
480        assert_eq!(Sha1::digest(update).as_slice(), hash);
481    }
482
483    #[test]
484    fn can_verify_sha1_cross_sector_boundary() {
485        let flash = Mutex::<NoopRawMutex, _>::new(RefCell::new(MemFlash::<131072, 1024, 8>::default()));
486        let state = BlockingPartition::new(&flash, 0, 4096);
487        let dfu = BlockingPartition::new(&flash, 65536, 65536);
488        let mut aligned = [0; 8];
489
490        let update = [0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66];
491        let mut to_write = [0; 4096];
492        to_write[..7].copy_from_slice(update.as_slice());
493
494        let mut updater = BlockingFirmwareUpdater::new(FirmwareUpdaterConfig { dfu, state }, &mut aligned);
495        let mut offset = 0;
496        for chunk in to_write.chunks(896) {
497            updater.write_firmware(offset, chunk).unwrap();
498            offset += chunk.len();
499        }
500        let mut chunk_buf = [0; 2];
501        let mut hash = [0; 20];
502        updater
503            .hash::<Sha1>(update.len() as u32, &mut chunk_buf, &mut hash)
504            .unwrap();
505
506        assert_eq!(Sha1::digest(update).as_slice(), hash);
507    }
508}
embassy_boot/firmware_updater/blocking.rs

embassy_boot/firmware_updater/
blocking.rs
