| // Licensed under the Apache-2.0 license | |
| // SPDX-License-Identifier: Apache-2.0 | |
| //! High-level blocking flash interface. | |
| #![cfg_attr(not(test), no_std)] | |
| use core::{cmp::min, num::NonZero}; | |
| pub use hal_flash_driver::FlashAddress; | |
| use hal_flash_driver::FlashDriver; | |
| use util_io::RandomRead; | |
| use util_types::{Blocking, PowerOf2Usize}; | |
| /// Length of the scratch buffer that holds the unaligned prefix of a | |
| /// read. A driver whose `READ_ALIGNMENT` exceeds `PREFIX_BUF_LEN` | |
| /// cannot use `BlockingFlash`. | |
| const PREFIX_BUF_LEN: usize = 16; | |
| /// High-level flash interface. | |
| /// | |
| /// This trait provides a simplified, synchronous, blocking interface for flash operations. | |
| /// It abstracts away the asynchronous execution model and hardware alignment/window | |
| /// constraints of the underlying driver. | |
| pub trait Flash { | |
| /// The error type returned by flash operations. | |
| type Error; | |
| /// Returns the geometry of the flash. | |
| /// | |
| /// # Returns | |
| /// A tuple containing: | |
| /// 1. The total size of the flash in bytes. | |
| /// 2. The default/smallest page size (erase block size) in bytes. | |
| /// 3. A bitmap of all supported erase block sizes. | |
| fn geometry(&mut self) -> Result<(NonZero<usize>, PowerOf2Usize, u32), Self::Error>; | |
| /// Reads data from flash into the provided buffer. | |
| /// | |
| /// This method handles unaligned read addresses by performing partial reads | |
| /// into a temporary buffer if necessary. | |
| /// | |
| /// # Arguments | |
| /// * `start_addr`: The address to start reading from. | |
| /// * `buf`: The buffer to read data into. | |
| fn read(&mut self, start_addr: FlashAddress, buf: &mut [u8]) -> Result<(), Self::Error>; | |
| /// Erases a block of flash. | |
| /// | |
| /// This is a blocking operation that waits for the hardware erase to complete. | |
| /// | |
| /// # Arguments | |
| /// * `start_addr`: The start address of the block to erase. Must be aligned to `size`. | |
| /// * `size`: The size of the block to erase. Must be one of the supported sizes in `geometry().2`. | |
| fn erase(&mut self, start_addr: FlashAddress, size: PowerOf2Usize) -> Result<(), Self::Error>; | |
| /// Programs data into flash. | |
| /// | |
| /// This is a blocking operation that waits for the hardware program to complete. | |
| /// It automatically handles programming data that spans across hardware program | |
| /// window boundaries by splitting it into multiple aligned writes. | |
| /// | |
| /// # Arguments | |
| /// * `start_addr`: The address to start programming at. | |
| /// * `data`: The data to program. | |
| fn program(&mut self, start_addr: FlashAddress, data: &[u8]) -> Result<(), Self::Error>; | |
| /// Returns a `RandomRead` implementation for this flash. | |
| fn random_reader(&mut self) -> impl RandomRead<Error = Self::Error> | |
| where | |
| Self: Sized, | |
| { | |
| FlashRandomReader(self) | |
| } | |
| } | |
| impl<F: Flash> Flash for &mut F { | |
| type Error = F::Error; | |
| #[inline(always)] | |
| fn geometry(&mut self) -> Result<(NonZero<usize>, PowerOf2Usize, u32), Self::Error> { | |
| (**self).geometry() | |
| } | |
| #[inline(always)] | |
| fn read(&mut self, start_addr: FlashAddress, buf: &mut [u8]) -> Result<(), Self::Error> { | |
| (**self).read(start_addr, buf) | |
| } | |
| #[inline(always)] | |
| fn program(&mut self, start_addr: FlashAddress, data: &[u8]) -> Result<(), Self::Error> { | |
| (**self).program(start_addr, data) | |
| } | |
| #[inline(always)] | |
| fn erase(&mut self, start_addr: FlashAddress, size: PowerOf2Usize) -> Result<(), Self::Error> { | |
| (**self).erase(start_addr, size) | |
| } | |
| } | |
| /// A trait that can be used to constrain the page-size of the flash. | |
| /// | |
| /// If you just need to read the page size at runtime, use `Flash::geometry()` instead. | |
| pub trait FlashPageSize { | |
| /// The size of a flash page in bytes. | |
| const PAGE_SIZE: usize; | |
| } | |
| /// A blocking flash implementation that wraps a `FlashDriver`. | |
| /// | |
| /// This struct implements the high-level `Flash` trait by wrapping a low-level | |
| /// `FlashDriver` and using a `Blocking` mechanism (e.g., waiting for an interrupt | |
| /// or polling) to block the calling thread until asynchronous driver operations | |
| /// complete. | |
| /// | |
| /// It also handles address alignment for reads and program window constraints for writes. | |
| pub struct BlockingFlash<TDriver: FlashDriver, TBlocking: Blocking> { | |
| /// The underlying flash driver. | |
| pub driver: TDriver, | |
| /// The blocking mechanism used to wait for operations. | |
| pub blocking: TBlocking, | |
| } | |
| impl<TDriver: FlashDriver, TBlocking: Blocking> FlashPageSize | |
| for BlockingFlash<TDriver, TBlocking> | |
| { | |
| /// The default page size. | |
| const PAGE_SIZE: usize = TDriver::PAGE_SIZE; | |
| } | |
| impl<TDriver: FlashDriver, TBlocking: Blocking> Flash for BlockingFlash<TDriver, TBlocking> { | |
| type Error = TDriver::Error; | |
| fn geometry(&mut self) -> Result<(NonZero<usize>, PowerOf2Usize, u32), Self::Error> { | |
| let bitmap = self.driver.erasable_sizes_bitmap()?; | |
| let page_size = PowerOf2Usize::from_shift(bitmap.trailing_zeros()); | |
| Ok((self.driver.size(), page_size, bitmap.get())) | |
| } | |
| /// Reads data from flash. | |
| /// | |
| /// Handles unaligned `start_addr` by reading the aligned block containing it | |
| /// into a temporary buffer first, copying the relevant bytes, and then reading | |
| /// the remaining data in aligned chunks. | |
| fn read(&mut self, start_addr: FlashAddress, mut buf: &mut [u8]) -> Result<(), Self::Error> { | |
| let mut addr = start_addr; | |
| let align_skip_len = (addr.offset() & (TDriver::READ_ALIGNMENT as u32 - 1)) as usize; | |
| if (align_skip_len) != 0 { | |
| // Read prefix up to alignment boundary | |
| const { assert!(TDriver::READ_ALIGNMENT <= PREFIX_BUF_LEN) }; | |
| let mut tmp = [0_u8; PREFIX_BUF_LEN]; | |
| let prefix_count = min(TDriver::READ_ALIGNMENT - align_skip_len, buf.len()); | |
| self.driver.read( | |
| addr & !(TDriver::READ_ALIGNMENT - 1), | |
| &mut tmp[..TDriver::READ_ALIGNMENT], | |
| )?; | |
| buf[..prefix_count].copy_from_slice(&tmp[align_skip_len..][..prefix_count]); | |
| buf = &mut buf[prefix_count..]; | |
| addr += prefix_count; | |
| } | |
| // Read remaining aligned chunks | |
| for buf_chunk in buf.chunks_mut(TDriver::MAX_READ_SIZE) { | |
| self.driver.read(addr, buf_chunk)?; | |
| addr += buf_chunk.len(); | |
| } | |
| Ok(()) | |
| } | |
| /// Erases a block of flash. | |
| /// | |
| /// Starts the asynchronous erase operation and blocks the thread using `self.blocking` | |
| /// until the operation completes. | |
| fn erase(&mut self, start_addr: FlashAddress, size: PowerOf2Usize) -> Result<(), Self::Error> { | |
| self.driver.start_erase(start_addr, size)?; | |
| self.blocking.wait_for_notification(); | |
| self.driver.complete_op() | |
| } | |
| /// Programs data into flash. | |
| /// | |
| /// Splits the data into chunks that fit within the hardware's `PROGRAM_WINDOW_SIZE` | |
| /// and do not cross window boundaries. Each chunk is programmed asynchronously, | |
| /// and the thread blocks until it completes before starting the next chunk. | |
| fn program(&mut self, start_addr: FlashAddress, mut data: &[u8]) -> Result<(), Self::Error> { | |
| let program_window_size = self.driver.program_window_size().get(); | |
| let window_mask = program_window_size - 1; | |
| let mut addr = start_addr; | |
| while !data.is_empty() { | |
| // Calculate bytes remaining in the current program window | |
| let chunk = &data[..min( | |
| data.len(), | |
| program_window_size - ((addr.offset() & window_mask as u32) as usize), | |
| )]; | |
| self.driver.start_program(addr, chunk)?; | |
| self.blocking.wait_for_notification(); | |
| self.driver.complete_op()?; | |
| data = &data[chunk.len()..]; | |
| addr += chunk.len(); | |
| } | |
| Ok(()) | |
| } | |
| } | |
| struct FlashRandomReader<'a, F: Flash>(&'a mut F); | |
| impl<F: Flash> RandomRead for FlashRandomReader<'_, F> { | |
| type Error = F::Error; | |
| fn read(&mut self, start_addr: usize, buf: &mut [u8]) -> Result<(), Self::Error> { | |
| self.0.read(FlashAddress::new(start_addr as u32), buf) | |
| } | |
| fn size(&mut self) -> Result<usize, Self::Error> { | |
| Ok(self.0.geometry()?.0.get()) | |
| } | |
| } | |
| #[cfg(test)] | |
| mod test { | |
| use super::*; | |
| pub struct FakeBlocking(); | |
| impl Blocking for FakeBlocking { | |
| fn wait_for_notification(&self) {} | |
| } | |
| #[derive(Debug, Clone, Copy)] | |
| pub struct FakeDriverError; | |
| #[derive(Clone)] | |
| pub struct FakeFlashDriver { | |
| pub data: Vec<u8>, | |
| pub check_err_result: Result<(), FakeDriverError>, | |
| } | |
| impl FakeFlashDriver { | |
| pub fn new(data: Vec<u8>) -> Self { | |
| Self { | |
| data, | |
| check_err_result: Ok(()), | |
| } | |
| } | |
| } | |
| impl FlashDriver for FakeFlashDriver { | |
| type Error = FakeDriverError; | |
| const PAGE_SIZE: usize = 2048; | |
| const PROGRAM_WINDOW_SIZE: usize = 64; | |
| const MAX_READ_SIZE: usize = 4096; | |
| const READ_ALIGNMENT: usize = 4; | |
| const PROGRAM_ALIGNMENT: usize = 8; | |
| fn erasable_sizes_bitmap(&mut self) -> Result<NonZero<u32>, Self::Error> { | |
| Ok(NonZero::new(1 << 11).unwrap()) | |
| } | |
| fn size(&self) -> NonZero<usize> { | |
| NonZero::new(self.data.len()).unwrap() | |
| } | |
| fn read(&mut self, start_addr: FlashAddress, buf: &mut [u8]) -> Result<(), Self::Error> { | |
| let start_addr = start_addr.offset() as usize; | |
| assert!(start_addr.checked_add(buf.len()).unwrap() <= self.data.len()); | |
| assert!(buf.len() <= Self::MAX_READ_SIZE); | |
| assert!(start_addr % Self::READ_ALIGNMENT == 0); | |
| buf.copy_from_slice(&self.data[start_addr..][..buf.len()]); | |
| Ok(()) | |
| } | |
| fn start_erase( | |
| &mut self, | |
| start_addr: FlashAddress, | |
| size: PowerOf2Usize, | |
| ) -> Result<(), Self::Error> { | |
| let start_addr = start_addr.offset() as usize; | |
| assert_eq!(size.get(), 2048); | |
| assert!(start_addr.checked_add(size.get()).unwrap() <= self.data.len()); | |
| assert!(start_addr % size.get() == 0); | |
| self.data[start_addr..][..size.get()].fill(0xff); | |
| Ok(()) | |
| } | |
| fn start_program( | |
| &mut self, | |
| start_addr: FlashAddress, | |
| data: &[u8], | |
| ) -> Result<(), Self::Error> { | |
| let start_addr = start_addr.offset() as usize; | |
| let program_window_size = self.program_window_size().get(); | |
| assert!(start_addr.checked_add(data.len()).unwrap() <= self.data.len()); | |
| assert!( | |
| data.len() <= program_window_size, | |
| "Program window violation" | |
| ); | |
| let end_addr = start_addr.wrapping_add(data.len()); | |
| assert!( | |
| start_addr / program_window_size == (end_addr - 1) / program_window_size, | |
| "Program window violation" | |
| ); | |
| for (dest, src) in self.data[start_addr..end_addr].iter_mut().zip(data) { | |
| *dest &= *src; | |
| } | |
| Ok(()) | |
| } | |
| fn is_busy(&mut self) -> bool { | |
| false | |
| } | |
| fn complete_op(&mut self) -> Result<(), Self::Error> { | |
| self.check_err_result | |
| } | |
| } | |
| #[test] | |
| #[should_panic(expected = "Program window violation")] | |
| pub fn test_fake_flash_program_window_violation_0() { | |
| let mut flash_driver = FakeFlashDriver::new((0..255).collect()); | |
| flash_driver | |
| .start_program(FlashAddress::new(0x3c), &[0x42; 5]) | |
| .unwrap(); | |
| } | |
| #[test] | |
| #[should_panic(expected = "Program window violation")] | |
| pub fn test_fake_flash_program_window_violation_1() { | |
| let mut flash_driver = FakeFlashDriver::new((0..255).collect()); | |
| flash_driver | |
| .start_program(FlashAddress::new(0x0), &[0; 68]) | |
| .unwrap(); | |
| } | |
| #[test] | |
| pub fn test_fake_flash_full_program_window() { | |
| let mut flash_driver = FakeFlashDriver::new((0..255).collect()); | |
| flash_driver | |
| .start_program(FlashAddress::new(0x40), &[0; 0x40]) | |
| .unwrap(); | |
| assert_eq!(flash_driver.data[0x40..0x80], [0; 0x40]); | |
| } | |
| #[test] | |
| pub fn test_size() { | |
| let flash_driver = FakeFlashDriver::new((0..255).collect()); | |
| let mut flash = BlockingFlash { | |
| driver: flash_driver, | |
| blocking: FakeBlocking(), | |
| }; | |
| assert_eq!(flash.geometry().unwrap().0.get(), 255); | |
| let mut reader = flash.random_reader(); | |
| assert_eq!(reader.size().unwrap(), 255); | |
| } | |
| #[test] | |
| pub fn test_read() { | |
| let flash_driver = FakeFlashDriver::new((0..255).collect()); | |
| let mut flash = BlockingFlash { | |
| driver: flash_driver, | |
| blocking: FakeBlocking(), | |
| }; | |
| let mut buf = [0_u8; 4]; | |
| flash.read(FlashAddress::new(0), &mut buf).unwrap(); | |
| assert_eq!(buf, [0_u8, 1, 2, 3]); | |
| let mut buf = [0_u8; 4]; | |
| flash.read(FlashAddress::new(1), &mut buf).unwrap(); | |
| assert_eq!(buf, [1, 2, 3, 4]); | |
| let mut buf = [0_u8; 4]; | |
| flash.read(FlashAddress::new(2), &mut buf).unwrap(); | |
| assert_eq!(buf, [2, 3, 4, 5]); | |
| { | |
| let mut reader = flash.random_reader(); | |
| let mut buf = [0_u8; 4]; | |
| reader.read(2, &mut buf).unwrap(); | |
| assert_eq!(buf, [2, 3, 4, 5]); | |
| } | |
| let mut buf = [0_u8; 4]; | |
| flash.read(FlashAddress::new(3), &mut buf).unwrap(); | |
| assert_eq!(buf, [3, 4, 5, 6]); | |
| let mut buf = [0_u8; 6]; | |
| flash.read(FlashAddress::new(3), &mut buf).unwrap(); | |
| assert_eq!(buf, [3, 4, 5, 6, 7, 8]); | |
| for i in 0..32 { | |
| let mut buf = [0_u8; 32]; | |
| flash.read(FlashAddress::new(0), &mut buf[..i]).unwrap(); | |
| assert_eq!(&buf[..i], &flash.driver.data[..i]); | |
| } | |
| for i in 0..32 { | |
| let mut buf = [0_u8; 32]; | |
| flash | |
| .read(FlashAddress::new(32 - i as u32), &mut buf[..i]) | |
| .unwrap(); | |
| assert_eq!(&buf[..i], &flash.driver.data[32 - i..32]); | |
| } | |
| } | |
| #[test] | |
| pub fn test_erase() { | |
| let mut flash = BlockingFlash { | |
| driver: FakeFlashDriver::new(vec![0x42; 0x4000]), | |
| blocking: FakeBlocking(), | |
| }; | |
| flash | |
| .erase(FlashAddress::new(0x0800), PowerOf2Usize::new(2048).unwrap()) | |
| .unwrap(); | |
| assert_eq!(flash.driver.data[0x0000..0x0800], [0x42; 0x0800]); | |
| assert_eq!(flash.driver.data[0x0800..0x1000], [0xff; 0x0800]); | |
| assert_eq!(flash.driver.data[0x1000..0x4000], [0x42; 0x3000]); | |
| flash | |
| .erase(FlashAddress::new(0x3000), PowerOf2Usize::new(2048).unwrap()) | |
| .unwrap(); | |
| assert_eq!(flash.driver.data[0x0000..0x0800], [0x42; 0x0800]); | |
| assert_eq!(flash.driver.data[0x0800..0x1000], [0xff; 0x0800]); | |
| assert_eq!(flash.driver.data[0x1000..0x3000], [0x42; 0x2000]); | |
| assert_eq!(flash.driver.data[0x3000..0x3800], [0xff; 0x0800]); | |
| assert_eq!(flash.driver.data[0x3800..0x4000], [0x42; 0x0800]); | |
| } | |
| #[test] | |
| pub fn test_program() { | |
| let mut flash = BlockingFlash { | |
| driver: FakeFlashDriver::new(vec![0xff; 8192]), | |
| blocking: FakeBlocking(), | |
| }; | |
| flash | |
| .program( | |
| FlashAddress::new(0x3c), | |
| &[0x10, 0x11, 0x12, 0x13, 0x14, 0x15], | |
| ) | |
| .unwrap(); | |
| assert_eq!( | |
| flash.driver.data[0x38..0x44], | |
| [0xff, 0xff, 0xff, 0xff, 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0xff, 0xff] | |
| ); | |
| flash | |
| .program(FlashAddress::new(0x40), &[0x24, 0x25]) | |
| .unwrap(); | |
| assert_eq!( | |
| flash.driver.data[0x38..0x44], | |
| [0xff, 0xff, 0xff, 0xff, 0x10, 0x11, 0x12, 0x13, 0x04, 0x05, 0xff, 0xff] | |
| ); | |
| } | |
| } |