FlashWriter.write requires additional user input

- FlashWriter.write used to automatically pad incoming data such that is
was divisible by 8, a requirement of the STM32 flash hardware. A
colleague suggested this could cause confusion during subsequent
writes. FlashWriter.write now forces the user to acknowledge this
with the `force_data_padding` flag. If true, the data will be padded
automatically to be divisible by 8. If false and the data is not
divisible by 8, an error is thrown.
- Added new error ArrayMustBeDivisibleBy8
- Modified the flash example based on the above updates

Author: amcelroy

examples/flash_with_rtic.rs

@@ -87,29 +87,72 @@ mod app {
         ];
         let mut flash = dp.FLASH.constrain();
         let mut flash_writer = flash.writer::<2048>(FlashSize::Sz256K);
-        const FLASH_SPACING: usize = 16; // Separate flash writes by 16 bytes
+        const FLASH_SPACING: u32 = 16; // Separate flash writes by 16 bytes
 
         flash_writer.erase(0x1FC00, 128).unwrap(); // Erase entire page
 
         for i in 0..6 {
             match i {
-                0 => flash_writer
-                    .write(0x1FC00 + i * FLASH_SPACING, &one_byte)
-                    .unwrap(),
-                1 => flash_writer
-                    .write(0x1FC00 + i * FLASH_SPACING, &two_bytes)
-                    .unwrap(),
-                2 => flash_writer
-                    .write(0x1FC00 + i * FLASH_SPACING, &three_bytes)
-                    .unwrap(),
-                3 => flash_writer
-                    .write(0x1FC00 + i * FLASH_SPACING, &four_bytes)
-                    .unwrap(),
+                0 => {
+                    // This test should fail, as the data needs to be divisible by 8 and force padding is false
+                    let result = flash_writer.write(0x1FC00 + i * FLASH_SPACING, &one_byte, false);
+                    assert!(result.is_err());
+                    assert_eq!(
+                        result.err().unwrap(),
+                        stm32g4xx_hal::flash::Error::ArrayMustBeDivisibleBy8
+                    );
+
+                    // This test should pass, as the data needs to be divisible by 8 and force padding is true, so the one_byte array will be padded with 7 bytes of 0xFF
+                    let result = flash_writer.write(0x1FC00 + i * FLASH_SPACING, &one_byte, true);
+                    assert!(result.is_ok());
+                }
+                1 => {
+                    // This test should fail, as the data needs to be divisible by 8 and force padding is false
+                    let result = flash_writer.write(0x1FC00 + i * FLASH_SPACING, &two_bytes, false);
+                    assert!(result.is_err());
+                    assert_eq!(
+                        result.err().unwrap(),
+                        stm32g4xx_hal::flash::Error::ArrayMustBeDivisibleBy8
+                    );
+
+                    // This test should pass, as the data needs to be divisible by 8 and force padding is true, so the one_byte array will be padded with 7 bytes of 0xFF
+                    let result = flash_writer.write(0x1FC00 + i * FLASH_SPACING, &two_bytes, true);
+                    assert!(result.is_ok());
+                }
+                2 => {
+                    // This test should fail, as the data needs to be divisible by 8 and force padding is false
+                    let result =
+                        flash_writer.write(0x1FC00 + i * FLASH_SPACING, &three_bytes, false);
+                    assert!(result.is_err());
+                    assert_eq!(
+                        result.err().unwrap(),
+                        stm32g4xx_hal::flash::Error::ArrayMustBeDivisibleBy8
+                    );
+
+                    // This test should pass, as the data needs to be divisible by 8 and force padding is true, so the one_byte array will be padded with 7 bytes of 0xFF
+                    let result =
+                        flash_writer.write(0x1FC00 + i * FLASH_SPACING, &three_bytes, true);
+                    assert!(result.is_ok());
+                }
+                3 => {
+                    // This test should fail, as the data needs to be divisible by 8 and force padding is false
+                    let result =
+                        flash_writer.write(0x1FC00 + i * FLASH_SPACING, &four_bytes, false);
+                    assert!(result.is_err());
+                    assert_eq!(
+                        result.err().unwrap(),
+                        stm32g4xx_hal::flash::Error::ArrayMustBeDivisibleBy8
+                    );
+
+                    // This test should pass, as the data needs to be divisible by 8 and force padding is true, so the one_byte array will be padded with 7 bytes of 0xFF
+                    let result = flash_writer.write(0x1FC00 + i * FLASH_SPACING, &four_bytes, true);
+                    assert!(result.is_ok());
+                }
                 4 => flash_writer
-                    .write(0x1FC00 + i * FLASH_SPACING, &eight_bytes)
+                    .write(0x1FC00 + i * FLASH_SPACING, &eight_bytes, false)
                     .unwrap(),
                 5 => flash_writer
-                    .write(0x1FC00 + i * 16, &sixteen_bytes)
+                    .write(0x1FC00 + i * 16, &sixteen_bytes, false)
                     .unwrap(),
                 _ => (),
             }

src/flash.rs

@@ -32,6 +32,7 @@ pub enum Error {
     OptUnlockError,
     LockError,
     OptLockError,
+    ArrayMustBeDivisibleBy8,
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Ord, PartialOrd)]
@@ -137,16 +138,20 @@ impl<'a, const SECTOR_SZ_KB: u32> FlashWriter<'a, SECTOR_SZ_KB> {
         }
     }
 
-    fn valid_length(&self, offset: u32, length: usize) -> Result<()> {
+    fn valid_length(&self, offset: u32, length: usize, force_padding: bool) -> Result<()> {
         if offset
             .checked_add(length as u32)
             .ok_or(Error::LengthTooLong)?
             > self.flash_sz.kbytes() as u32
         {
-            Err(Error::LengthTooLong)
-        } else {
-            Ok(())
+            return Err(Error::LengthTooLong);
+        }
+
+        if force_padding == false && length % 8 != 0 {
+            return Err(Error::ArrayMustBeDivisibleBy8);
         }
+
+        Ok(())
     }
 
     /// Erase sector which contains `start_offset`
@@ -215,7 +220,7 @@ impl<'a, const SECTOR_SZ_KB: u32> FlashWriter<'a, SECTOR_SZ_KB> {
 
     /// Erase the Flash Sectors from `FLASH_START + start_offset` to `length`
     pub fn erase(&mut self, start_offset: u32, length: usize) -> Result<()> {
-        self.valid_length(start_offset, length)?;
+        self.valid_length(start_offset, length, true)?;
 
         // Erase every sector touched by start_offset + length
         for offset in
@@ -248,9 +253,14 @@ impl<'a, const SECTOR_SZ_KB: u32> FlashWriter<'a, SECTOR_SZ_KB> {
         )
     }
 
-    /// Write data to `FLASH_START + offset`
-    pub fn write(&mut self, offset: u32, data: &[u8]) -> Result<()> {
-        self.valid_length(offset, data.len())?;
+    /// Write data to `FLASH_START + offset`.
+    ///
+    /// If `force_data_padding` is true, the incoming data will be padded with 0xFF
+    /// to satisfy the requirement that 2 words (8 bytes) must be written at a time.
+    /// If `force_data_padding` is false and `data.len()` is not divisible by 8,
+    /// the error `ArrayMustBeDivisibleBy8` will be returned.
+    pub fn write(&mut self, offset: u32, data: &[u8], force_data_padding: bool) -> Result<()> {
+        self.valid_length(offset, data.len(), force_data_padding)?;
 
         // Unlock Flash
         self.unlock()?;