stm32: add some docs.

embassy-stm32/src/flash/mod.rs

@@ -14,50 +14,84 @@ pub use crate::_generated::flash_regions::*;
 pub use crate::_generated::MAX_ERASE_SIZE;
 pub use crate::pac::{FLASH_BASE, FLASH_SIZE, WRITE_SIZE};
 
+/// Get whether the default flash layout is being used.
+///
+/// In some chips, dual-bank is not default. This will then return `false`
+/// when dual-bank is enabled.
+pub fn is_default_layout() -> bool {
+    family::is_default_layout()
+}
+
+/// Get all flash regions.
+pub fn get_flash_regions() -> &'static [&'static FlashRegion] {
+    family::get_flash_regions()
+}
+
+/// Read size (always 1)
 pub const READ_SIZE: usize = 1;
 
-pub struct Blocking;
-pub struct Async;
+/// Blocking flash mode typestate.
+pub enum Blocking {}
+/// Async flash mode typestate.
+pub enum Async {}
 
+/// Flash memory region
 #[derive(Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct FlashRegion {
+    /// Bank number.
     pub bank: FlashBank,
+    /// Absolute base address.
     pub base: u32,
+    /// Size in bytes.
     pub size: u32,
+    /// Erase size (sector size).
     pub erase_size: u32,
+    /// Minimum write size.
     pub write_size: u32,
+    /// Erase value (usually `0xFF`, but is `0x00` in some chips)
     pub erase_value: u8,
     pub(crate) _ensure_internal: (),
 }
 
-#[derive(Debug, PartialEq)]
-#[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct FlashSector {
-    pub bank: FlashBank,
-    pub index_in_bank: u8,
-    pub start: u32,
-    pub size: u32,
-}
-
-#[derive(Clone, Copy, Debug, PartialEq)]
-#[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub enum FlashBank {
-    Bank1 = 0,
-    Bank2 = 1,
-    Otp,
-}
-
 impl FlashRegion {
+    /// Absolute end address.
     pub const fn end(&self) -> u32 {
         self.base + self.size
     }
 
+    /// Number of sectors in the region.
     pub const fn sectors(&self) -> u8 {
         (self.size / self.erase_size) as u8
     }
 }
 
+/// Flash sector.
+#[derive(Debug, PartialEq)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+pub struct FlashSector {
+    /// Bank number.
+    pub bank: FlashBank,
+    /// Sector number within the bank.
+    pub index_in_bank: u8,
+    /// Absolute start address.
+    pub start: u32,
+    /// Size in bytes.
+    pub size: u32,
+}
+
+/// Flash bank.
+#[derive(Clone, Copy, Debug, PartialEq)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+pub enum FlashBank {
+    /// Bank 1
+    Bank1 = 0,
+    /// Bank 2
+    Bank2 = 1,
+    /// OTP region
+    Otp,
+}
+
 #[cfg_attr(any(flash_l0, flash_l1, flash_l4, flash_wl, flash_wb), path = "l.rs")]
 #[cfg_attr(flash_f0, path = "f0.rs")]
 #[cfg_attr(flash_f3, path = "f3.rs")]
@@ -78,6 +112,10 @@ mod family;
 #[allow(unused_imports)]
 pub use family::*;
 
+/// Flash error
+///
+/// See STM32 Reference Manual for your chip for details.
+#[allow(missing_docs)]
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Error {