stm32: update stm32-metapac. Fixes USB on STM32WB.

docs: document all public apis of embedded-hal-internal

embassy-hal-internal/src/atomic_ring_buffer.rs

@@ -1,3 +1,4 @@
+//! Atomic reusable ringbuffer.
 use core::slice;
 use core::sync::atomic::{AtomicPtr, AtomicUsize, Ordering};
 
@@ -14,8 +15,9 @@ use core::sync::atomic::{AtomicPtr, AtomicUsize, Ordering};
 /// One concurrent writer and one concurrent reader are supported, even at
 /// different execution priorities (like main and irq).
 pub struct RingBuffer {
+    #[doc(hidden)]
     pub buf: AtomicPtr<u8>,
-    pub len: AtomicUsize,
+    len: AtomicUsize,
 
     // start and end wrap at len*2, not at len.
     // This allows distinguishing "full" and "empty".
@@ -24,11 +26,16 @@ pub struct RingBuffer {
     //
     // This avoids having to consider the ringbuffer "full" at len-1 instead of len.
     // The usual solution is adding a "full" flag, but that can't be made atomic
+    #[doc(hidden)]
     pub start: AtomicUsize,
+    #[doc(hidden)]
     pub end: AtomicUsize,
 }
 
+/// A type which can only read from a ring buffer.
 pub struct Reader<'a>(&'a RingBuffer);
+
+/// A type which can only write to a ring buffer.
 pub struct Writer<'a>(&'a RingBuffer);
 
 impl RingBuffer {
@@ -89,10 +96,12 @@ impl RingBuffer {
         Writer(self)
     }
 
+    /// Return length of buffer.
     pub fn len(&self) -> usize {
         self.len.load(Ordering::Relaxed)
     }
 
+    /// Check if buffer is full.
     pub fn is_full(&self) -> bool {
         let len = self.len.load(Ordering::Relaxed);
         let start = self.start.load(Ordering::Relaxed);
@@ -101,6 +110,7 @@ impl RingBuffer {
         self.wrap(start + len) == end
     }
 
+    /// Check if buffer is empty.
     pub fn is_empty(&self) -> bool {
         let start = self.start.load(Ordering::Relaxed);
         let end = self.end.load(Ordering::Relaxed);
@@ -238,6 +248,7 @@ impl<'a> Writer<'a> {
         [(unsafe { buf.add(end) }, n0), (buf, n1)]
     }
 
+    /// Mark n bytes as written and advance the write index.
     pub fn push_done(&mut self, n: usize) {
         trace!("  ringbuf: push {:?}", n);
         let end = self.0.end.load(Ordering::Relaxed);
@@ -323,6 +334,7 @@ impl<'a> Reader<'a> {
         (unsafe { buf.add(start) }, n)
     }
 
+    /// Mark n bytes as read and allow advance the read index.
     pub fn pop_done(&mut self, n: usize) {
         trace!("  ringbuf: pop {:?}", n);
 

embassy-hal-internal/src/drop.rs

@@ -1,16 +1,20 @@
+//! Types for controlling when drop is invoked.
 use core::mem;
 use core::mem::MaybeUninit;
 
-#[must_use = "to delay the drop handler invokation to the end of the scope"]
+/// A type to delay the drop handler invocation.
+#[must_use = "to delay the drop handler invocation to the end of the scope"]
 pub struct OnDrop<F: FnOnce()> {
     f: MaybeUninit<F>,
 }
 
 impl<F: FnOnce()> OnDrop<F> {
+    /// Create a new instance.
     pub fn new(f: F) -> Self {
         Self { f: MaybeUninit::new(f) }
     }
 
+    /// Prevent drop handler from running.
     pub fn defuse(self) {
         mem::forget(self)
     }
@@ -34,6 +38,7 @@ pub struct DropBomb {
 }
 
 impl DropBomb {
+    /// Create a new instance.
     pub fn new() -> Self {
         Self { _private: () }
     }

embassy-hal-internal/src/lib.rs

@@ -1,6 +1,7 @@
 #![no_std]
 #![allow(clippy::new_without_default)]
 #![doc = include_str!("../README.md")]
+#![warn(missing_docs)]
 
 // This mod MUST go first, so that the others see its macros.
 pub(crate) mod fmt;

embassy-hal-internal/src/macros.rs

@@ -1,3 +1,4 @@
+/// Types for the peripheral singletons.
 #[macro_export]
 macro_rules! peripherals_definition {
     ($($(#[$cfg:meta])? $name:ident),*$(,)?) => {
@@ -29,6 +30,7 @@ macro_rules! peripherals_definition {
     };
 }
 
+/// Define the peripherals struct.
 #[macro_export]
 macro_rules! peripherals_struct {
     ($($(#[$cfg:meta])? $name:ident),*$(,)?) => {
@@ -87,6 +89,7 @@ macro_rules! peripherals_struct {
     };
 }
 
+/// Defining peripheral type.
 #[macro_export]
 macro_rules! peripherals {
     ($($(#[$cfg:meta])? $name:ident),*$(,)?) => {
@@ -105,6 +108,7 @@ macro_rules! peripherals {
     };
 }
 
+/// Convenience converting into reference.
 #[macro_export]
 macro_rules! into_ref {
     ($($name:ident),*) => {
@@ -114,6 +118,7 @@ macro_rules! into_ref {
     }
 }
 
+/// Implement the peripheral trait.
 #[macro_export]
 macro_rules! impl_peripheral {
     ($type:ident) => {

embassy-hal-internal/src/peripheral.rs

@@ -20,6 +20,7 @@ pub struct PeripheralRef<'a, T> {
 }
 
 impl<'a, T> PeripheralRef<'a, T> {
+    /// Create a new reference to a peripheral.
     #[inline]
     pub fn new(inner: T) -> Self {
         Self {

embassy-hal-internal/src/ratio.rs

@@ -1,3 +1,4 @@
+//! Types for dealing with rational numbers.
 use core::ops::{Add, Div, Mul};
 
 use num_traits::{CheckedAdd, CheckedDiv, CheckedMul};

embassy-stm32/Cargo.toml

@@ -58,7 +58,7 @@ rand_core = "0.6.3"
 sdio-host = "0.5.0"
 embedded-sdmmc = { git = "https://github.com/embassy-rs/embedded-sdmmc-rs", rev = "a4f293d3a6f72158385f79c98634cb8a14d0d2fc", optional = true }
 critical-section = "1.1"
-stm32-metapac = { git = "https://github.com/embassy-rs/stm32-data-generated", tag = "stm32-data-019a5da1c47c092c199bc39a7f84fb444f2adcdf" }
+stm32-metapac = { git = "https://github.com/embassy-rs/stm32-data-generated", tag = "stm32-data-8f5fcae8c289c1ad481cc3a2bb37db023a61599c" }
 vcell = "0.1.3"
 bxcan = "0.7.0"
 nb = "1.0.0"
@@ -76,7 +76,7 @@ critical-section = { version = "1.1", features = ["std"] }
 [build-dependencies]
 proc-macro2 = "1.0.36"
 quote = "1.0.15"
-stm32-metapac = { git = "https://github.com/embassy-rs/stm32-data-generated", tag = "stm32-data-019a5da1c47c092c199bc39a7f84fb444f2adcdf", default-features = false, features = ["metadata"]}
+stm32-metapac = { git = "https://github.com/embassy-rs/stm32-data-generated", tag = "stm32-data-8f5fcae8c289c1ad481cc3a2bb37db023a61599c", default-features = false, features = ["metadata"]}
 
 
 [features]

embassy-stm32/src/rcc/g4.rs

@@ -308,6 +308,7 @@ pub(crate) unsafe fn init(config: Config) {
         sys: sys_clk,
         hclk1: ahb_freq,
         hclk2: ahb_freq,
+        hclk3: ahb_freq,
         pclk1: apb1_freq,
         pclk1_tim: apb1_tim_freq,
         pclk2: apb2_freq,

embassy-stm32/src/rcc/mod.rs

@@ -95,6 +95,7 @@ pub struct Clocks {
         rcc_h7rm0433,
         rcc_h7ab,
         rcc_u5,
+        rcc_g4,
         rcc_wb,
         rcc_wl5,
         rcc_wle