Merge remote-tracking branch 'origin'

author: sodo <[email protected]> 2024-01-02 01:37:00 +0900
committer: sodo <[email protected]> 2024-01-02 13:34:22 +0900
commit: 6ee153a3e2eec284c0d9d87f31801265c0604f74 (patch)
tree: 8b801cbd15f9ad5052d5942c731e75736dc9d7eb /embassy-stm32/src
parent: b7cd7952c890f585ff876c622482534e5d58d4a4 (diff)
parent: 0be9b0599aaf2e425d76ec7852ff4b3535defddf (diff)
74 files changed, 2032 insertions, 1351 deletions
diff --git a/embassy-stm32/src/adc/mod.rs b/embassy-stm32/src/adc/mod.rs
index dbe53c807..e4dd35c34 100644
--- a/embassy-stm32/src/adc/mod.rs
+++ b/embassy-stm32/src/adc/mod.rs
@@ -1,4 +1,7 @@
+//! Analog to Digital Converter (ADC)
 #![macro_use]
+#![allow(missing_docs)] // TODO
 #[cfg(not(adc_f3_v2))]
 #[cfg_attr(adc_f1, path = "f1.rs")]
@@ -24,6 +27,7 @@ pub use sample_time::SampleTime;
 use crate::peripherals;
+/// Analog to Digital driver.
 pub struct Adc<'d, T: Instance> {
    #[allow(unused)]
    adc: crate::PeripheralRef<'d, T>,
@@ -75,12 +79,16 @@ pub(crate) mod sealed {
    }
 }
+/// ADC instance.
 #[cfg(not(any(adc_f1, adc_v1, adc_v2, adc_v3, adc_v4, adc_f3, adc_f3_v1_1, adc_g0)))]
 pub trait Instance: sealed::Instance + crate::Peripheral<P = Self> {}
+/// ADC instance.
 #[cfg(any(adc_f1, adc_v1, adc_v2, adc_v3, adc_v4, adc_f3, adc_f3_v1_1, adc_g0))]
 pub trait Instance: sealed::Instance + crate::Peripheral<P = Self> + crate::rcc::RccPeripheral {}
+/// ADC pin.
 pub trait AdcPin<T: Instance>: sealed::AdcPin<T> {}
+/// ADC internal channel.
 pub trait InternalChannel<T>: sealed::InternalChannel<T> {}
 foreach_adc!(
diff --git a/embassy-stm32/src/adc/resolution.rs b/embassy-stm32/src/adc/resolution.rs
index 383980b5a..64c25a776 100644
--- a/embassy-stm32/src/adc/resolution.rs
+++ b/embassy-stm32/src/adc/resolution.rs
@@ -1,3 +1,5 @@
+/// ADC resolution
+#[allow(missing_docs)]
 #[cfg(any(adc_v1, adc_v2, adc_v3, adc_g0, adc_f3, adc_f3_v1_1))]
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
@@ -8,6 +10,8 @@ pub enum Resolution {
    SixBit,
 }
+/// ADC resolution
+#[allow(missing_docs)]
 #[cfg(adc_v4)]
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
@@ -49,6 +53,9 @@ impl From<Resolution> for crate::pac::adc::vals::Res {
 }
 impl Resolution {
+    /// Get the maximum reading value for this resolution.
+    ///
+    /// This is `2**n - 1`.
    pub fn to_max_count(&self) -> u32 {
        match self {
            #[cfg(adc_v4)]
diff --git a/embassy-stm32/src/adc/v4.rs b/embassy-stm32/src/adc/v4.rs
index d74617cb3..048e73184 100644
--- a/embassy-stm32/src/adc/v4.rs
+++ b/embassy-stm32/src/adc/v4.rs
@@ -32,6 +32,7 @@ const TEMP_CHANNEL: u8 = 18;
 const VBAT_CHANNEL: u8 = 17;
 // NOTE: Vrefint/Temperature/Vbat are not available on all ADCs, this currently cannot be modeled with stm32-data, so these are available from the software on all ADCs
+/// Internal voltage reference channel.
 pub struct VrefInt;
 impl<T: Instance> InternalChannel<T> for VrefInt {}
 impl<T: Instance> super::sealed::InternalChannel<T> for VrefInt {
@@ -40,6 +41,7 @@ impl<T: Instance> super::sealed::InternalChannel<T> for VrefInt {
    }
 }
+/// Internal temperature channel.
 pub struct Temperature;
 impl<T: Instance> InternalChannel<T> for Temperature {}
 impl<T: Instance> super::sealed::InternalChannel<T> for Temperature {
@@ -48,6 +50,7 @@ impl<T: Instance> super::sealed::InternalChannel<T> for Temperature {
    }
 }
+/// Internal battery voltage channel.
 pub struct Vbat;
 impl<T: Instance> InternalChannel<T> for Vbat {}
 impl<T: Instance> super::sealed::InternalChannel<T> for Vbat {
@@ -125,6 +128,7 @@ impl Prescaler {
 }
 impl<'d, T: Instance> Adc<'d, T> {
+    /// Create a new ADC driver.
    pub fn new(adc: impl Peripheral<P = T> + 'd, delay: &mut impl DelayUs<u16>) -> Self {
        embassy_hal_internal::into_ref!(adc);
        T::enable_and_reset();
@@ -212,6 +216,7 @@ impl<'d, T: Instance> Adc<'d, T> {
        });
    }
+    /// Enable reading the voltage reference internal channel.
    pub fn enable_vrefint(&self) -> VrefInt {
        T::common_regs().ccr().modify(|reg| {
            reg.set_vrefen(true);
@@ -220,6 +225,7 @@ impl<'d, T: Instance> Adc<'d, T> {
        VrefInt {}
    }
+    /// Enable reading the temperature internal channel.
    pub fn enable_temperature(&self) -> Temperature {
        T::common_regs().ccr().modify(|reg| {
            reg.set_vsenseen(true);
@@ -228,6 +234,7 @@ impl<'d, T: Instance> Adc<'d, T> {
        Temperature {}
    }
+    /// Enable reading the vbat internal channel.
    pub fn enable_vbat(&self) -> Vbat {
        T::common_regs().ccr().modify(|reg| {
            reg.set_vbaten(true);
@@ -236,10 +243,12 @@ impl<'d, T: Instance> Adc<'d, T> {
        Vbat {}
    }
+    /// Set the ADC sample time.
    pub fn set_sample_time(&mut self, sample_time: SampleTime) {
        self.sample_time = sample_time;
    }
+    /// Set the ADC resolution.
    pub fn set_resolution(&mut self, resolution: Resolution) {
        T::regs().cfgr().modify(|reg| reg.set_res(resolution.into()));
    }
@@ -263,6 +272,7 @@ impl<'d, T: Instance> Adc<'d, T> {
        T::regs().dr().read().0 as u16
    }
+    /// Read an ADC pin.
    pub fn read<P>(&mut self, pin: &mut P) -> u16
    where
        P: AdcPin<T>,
@@ -273,6 +283,7 @@ impl<'d, T: Instance> Adc<'d, T> {
        self.read_channel(pin.channel())
    }
+    /// Read an ADC internal channel.
    pub fn read_internal(&mut self, channel: &mut impl InternalChannel<T>) -> u16 {
        self.read_channel(channel.channel())
    }
diff --git a/embassy-stm32/src/can/bxcan.rs b/embassy-stm32/src/can/bxcan.rs
index 2f7417340..cc87b2565 100644
--- a/embassy-stm32/src/can/bxcan.rs
+++ b/embassy-stm32/src/can/bxcan.rs
@@ -1,3 +1,4 @@
+use core::convert::AsMut;
 use core::future::poll_fn;
 use core::marker::PhantomData;
 use core::ops::{Deref, DerefMut};
@@ -10,7 +11,7 @@ use futures::FutureExt;
 use crate::gpio::sealed::AFType;
 use crate::interrupt::typelevel::Interrupt;
-use crate::pac::can::vals::{Lec, RirIde};
+use crate::pac::can::vals::{Ide, Lec};
 use crate::rcc::RccPeripheral;
 use crate::time::Hertz;
 use crate::{interrupt, peripherals, Peripheral};
@@ -21,8 +22,10 @@ use crate::{interrupt, peripherals, Peripheral};
 #[derive(Debug, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct Envelope {
+    /// Reception time.
    #[cfg(feature = "time")]
    pub ts: embassy_time::Instant,
+    /// The actual CAN frame.
    pub frame: bxcan::Frame,
 }
@@ -43,6 +46,7 @@ impl<T: Instance> interrupt::typelevel::Handler<T::TXInterrupt> for TxInterruptH
    }
 }
+/// RX0 interrupt handler.
 pub struct Rx0InterruptHandler<T: Instance> {
    _phantom: PhantomData<T>,
 }
@@ -54,6 +58,7 @@ impl<T: Instance> interrupt::typelevel::Handler<T::RX0Interrupt> for Rx0Interrup
    }
 }
+/// RX1 interrupt handler.
 pub struct Rx1InterruptHandler<T: Instance> {
    _phantom: PhantomData<T>,
 }
@@ -65,6 +70,7 @@ impl<T: Instance> interrupt::typelevel::Handler<T::RX1Interrupt> for Rx1Interrup
    }
 }
+/// SCE interrupt handler.
 pub struct SceInterruptHandler<T: Instance> {
    _phantom: PhantomData<T>,
 }
@@ -82,10 +88,13 @@ impl<T: Instance> interrupt::typelevel::Handler<T::SCEInterrupt> for SceInterrup
    }
 }
+/// CAN driver
 pub struct Can<'d, T: Instance> {
-    pub can: bxcan::Can<BxcanInstance<'d, T>>,
+    can: bxcan::Can<BxcanInstance<'d, T>>,
 }
+/// CAN bus error
+#[allow(missing_docs)]
 #[derive(Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum BusError {
@@ -101,6 +110,7 @@ pub enum BusError {
    BusWarning,
 }
+/// Error returned by `try_read`
 #[derive(Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum TryReadError {
@@ -110,6 +120,7 @@ pub enum TryReadError {
    Empty,
 }
+/// Error returned by `try_write`
 #[derive(Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum TryWriteError {
@@ -138,15 +149,11 @@ impl<'d, T: Instance> Can<'d, T> {
        T::enable_and_reset();
        {
-            use crate::pac::can::vals::{Errie, Fmpie, Tmeie};
            T::regs().ier().write(|w| {
-                // TODO: fix metapac
+                w.set_errie(true);
+                w.set_fmpie(0, true);
-                w.set_errie(Errie::from_bits(1));
+                w.set_fmpie(1, true);
-                w.set_fmpie(0, Fmpie::from_bits(1));
+                w.set_tmeie(true);
-                w.set_fmpie(1, Fmpie::from_bits(1));
-                w.set_tmeie(Tmeie::from_bits(1));
            });
            T::regs().mcr().write(|w| {
@@ -177,6 +184,7 @@ impl<'d, T: Instance> Can<'d, T> {
        Self { can }
    }
+    /// Set CAN bit rate.
    pub fn set_bitrate(&mut self, bitrate: u32) {
        let bit_timing = Self::calc_bxcan_timings(T::frequency(), bitrate).unwrap();
        self.can.modify_config().set_bit_timing(bit_timing).leave_disabled();
@@ -194,7 +202,9 @@ impl<'d, T: Instance> Can<'d, T> {
        }
    }
-    /// Queues the message to be sent but exerts backpressure
+    /// Queues the message to be sent.
+    ///
+    /// If the TX queue is full, this will wait until there is space, therefore exerting backpressure.
    pub async fn write(&mut self, frame: &Frame) -> bxcan::TransmitStatus {
        self.split().0.write(frame).await
    }
@@ -221,12 +231,16 @@ impl<'d, T: Instance> Can<'d, T> {
        CanTx::<T>::flush_all_inner().await
    }
+    /// Read a CAN frame.
+    ///
+    /// If no CAN frame is in the RX buffer, this will wait until there is one.
+    ///
    /// Returns a tuple of the time the message was received and the message frame
    pub async fn read(&mut self) -> Result<Envelope, BusError> {
        self.split().1.read().await
    }
-    /// Attempts to read a can frame without blocking.
+    /// Attempts to read a CAN frame without blocking.
    ///
    /// Returns [Err(TryReadError::Empty)] if there are no frames in the rx queue.
    pub fn try_read(&mut self) -> Result<Envelope, TryReadError> {
@@ -259,7 +273,7 @@ impl<'d, T: Instance> Can<'d, T> {
            }
            let rir = fifo.rir().read();
-            let id = if rir.ide() == RirIde::STANDARD {
+            let id = if rir.ide() == Ide::STANDARD {
                Id::from(StandardId::new_unchecked(rir.stid()))
            } else {
                let stid = (rir.stid() & 0x7FF) as u32;
@@ -288,7 +302,7 @@ impl<'d, T: Instance> Can<'d, T> {
        }
    }
-    pub const fn calc_bxcan_timings(periph_clock: Hertz, can_bitrate: u32) -> Option<u32> {
+    const fn calc_bxcan_timings(periph_clock: Hertz, can_bitrate: u32) -> Option<u32> {
        const BS1_MAX: u8 = 16;
        const BS2_MAX: u8 = 8;
        const MAX_SAMPLE_POINT_PERMILL: u16 = 900;
@@ -379,21 +393,31 @@ impl<'d, T: Instance> Can<'d, T> {
        Some((sjw - 1) << 24 | (bs1 as u32 - 1) << 16 | (bs2 as u32 - 1) << 20 | (prescaler - 1))
    }
+    /// Split the CAN driver into transmit and receive halves.
+    ///
+    /// Useful for doing separate transmit/receive tasks.
    pub fn split<'c>(&'c mut self) -> (CanTx<'c, 'd, T>, CanRx<'c, 'd, T>) {
        let (tx, rx0, rx1) = self.can.split_by_ref();
        (CanTx { tx }, CanRx { rx0, rx1 })
    }
+}
-    pub fn as_mut(&mut self) -> &mut bxcan::Can<BxcanInstance<'d, T>> {
+impl<'d, T: Instance> AsMut<bxcan::Can<BxcanInstance<'d, T>>> for Can<'d, T> {
+    /// Get mutable access to the lower-level driver from the `bxcan` crate.
+    fn as_mut(&mut self) -> &mut bxcan::Can<BxcanInstance<'d, T>> {
        &mut self.can
    }
 }
+/// CAN driver, transmit half.
 pub struct CanTx<'c, 'd, T: Instance> {
    tx: &'c mut bxcan::Tx<BxcanInstance<'d, T>>,
 }
 impl<'c, 'd, T: Instance> CanTx<'c, 'd, T> {
+    /// Queues the message to be sent.
+    ///
+    /// If the TX queue is full, this will wait until there is space, therefore exerting backpressure.
    pub async fn write(&mut self, frame: &Frame) -> bxcan::TransmitStatus {
        poll_fn(|cx| {
            T::state().tx_waker.register(cx.waker());
@@ -475,6 +499,7 @@ impl<'c, 'd, T: Instance> CanTx<'c, 'd, T> {
    }
 }
+/// CAN driver, receive half.
 #[allow(dead_code)]
 pub struct CanRx<'c, 'd, T: Instance> {
    rx0: &'c mut bxcan::Rx0<BxcanInstance<'d, T>>,
@@ -482,6 +507,11 @@ pub struct CanRx<'c, 'd, T: Instance> {
 }
 impl<'c, 'd, T: Instance> CanRx<'c, 'd, T> {
+    /// Read a CAN frame.
+    ///
+    /// If no CAN frame is in the RX buffer, this will wait until there is one.
+    ///
+    /// Returns a tuple of the time the message was received and the message frame
    pub async fn read(&mut self) -> Result<Envelope, BusError> {
        poll_fn(|cx| {
            T::state().err_waker.register(cx.waker());
@@ -585,30 +615,24 @@ pub(crate) mod sealed {
    pub trait Instance {
        const REGISTERS: *mut bxcan::RegisterBlock;
-        fn regs() -> &'static crate::pac::can::Can;
+        fn regs() -> crate::pac::can::Can;
        fn state() -> &'static State;
    }
 }
-pub trait TXInstance {
+/// CAN instance trait.
+pub trait Instance: sealed::Instance + RccPeripheral + 'static {
+    /// TX interrupt for this instance.
    type TXInterrupt: crate::interrupt::typelevel::Interrupt;
-}
+    /// RX0 interrupt for this instance.
-pub trait RX0Instance {
    type RX0Interrupt: crate::interrupt::typelevel::Interrupt;
-}
+    /// RX1 interrupt for this instance.
-pub trait RX1Instance {
    type RX1Interrupt: crate::interrupt::typelevel::Interrupt;
-}
+    /// SCE interrupt for this instance.
-pub trait SCEInstance {
    type SCEInterrupt: crate::interrupt::typelevel::Interrupt;
 }
-pub trait InterruptableInstance: TXInstance + RX0Instance + RX1Instance + SCEInstance {}
+/// BXCAN instance newtype.
-pub trait Instance: sealed::Instance + RccPeripheral + InterruptableInstance + 'static {}
 pub struct BxcanInstance<'a, T>(PeripheralRef<'a, T>);
 unsafe impl<'d, T: Instance> bxcan::Instance for BxcanInstance<'d, T> {
@@ -620,8 +644,8 @@ foreach_peripheral!(
        impl sealed::Instance for peripherals::$inst {
            const REGISTERS: *mut bxcan::RegisterBlock = crate::pac::$inst.as_ptr() as *mut _;
-            fn regs() -> &'static crate::pac::can::Can {
+            fn regs() -> crate::pac::can::Can {
-                &crate::pac::$inst
+                crate::pac::$inst
            }
            fn state() -> &'static sealed::State {
@@ -630,32 +654,12 @@ foreach_peripheral!(
            }
        }
-        impl Instance for peripherals::$inst {}
+        impl Instance for peripherals::$inst {
+            type TXInterrupt = crate::_generated::peripheral_interrupts::$inst::TX;
-        foreach_interrupt!(
+            type RX0Interrupt = crate::_generated::peripheral_interrupts::$inst::RX0;
-            ($inst,can,CAN,TX,$irq:ident) => {
+            type RX1Interrupt = crate::_generated::peripheral_interrupts::$inst::RX1;
-                impl TXInstance for peripherals::$inst {
+            type SCEInterrupt = crate::_generated::peripheral_interrupts::$inst::SCE;
-                    type TXInterrupt = crate::interrupt::typelevel::$irq;
+        }
-                }
-            };
-            ($inst,can,CAN,RX0,$irq:ident) => {
-                impl RX0Instance for peripherals::$inst {
-                    type RX0Interrupt = crate::interrupt::typelevel::$irq;
-                }
-            };
-            ($inst,can,CAN,RX1,$irq:ident) => {
-                impl RX1Instance for peripherals::$inst {
-                    type RX1Interrupt = crate::interrupt::typelevel::$irq;
-                }
-            };
-            ($inst,can,CAN,SCE,$irq:ident) => {
-                impl SCEInstance for peripherals::$inst {
-                    type SCEInterrupt = crate::interrupt::typelevel::$irq;
-                }
-            };
-        );
-        impl InterruptableInstance for peripherals::$inst {}
    };
 );
diff --git a/embassy-stm32/src/can/fdcan.rs b/embassy-stm32/src/can/fdcan.rs
index f77788db3..0cc2559cf 100644
--- a/embassy-stm32/src/can/fdcan.rs
+++ b/embassy-stm32/src/can/fdcan.rs
@@ -1,6 +1,3 @@
-pub use bxcan;
-use embassy_hal_internal::PeripheralRef;
 use crate::peripherals;
 pub(crate) mod sealed {
@@ -25,27 +22,19 @@ pub(crate) mod sealed {
    }
    pub trait Instance {
-        const REGISTERS: *mut bxcan::RegisterBlock;
        fn regs() -> &'static crate::pac::can::Fdcan;
        fn state() -> &'static State;
    }
 }
+/// Interruptable FDCAN instance.
 pub trait InterruptableInstance {}
+/// FDCAN instance.
 pub trait Instance: sealed::Instance + InterruptableInstance + 'static {}
-pub struct BxcanInstance<'a, T>(PeripheralRef<'a, T>);
-unsafe impl<'d, T: Instance> bxcan::Instance for BxcanInstance<'d, T> {
-    const REGISTERS: *mut bxcan::RegisterBlock = T::REGISTERS;
-}
 foreach_peripheral!(
    (can, $inst:ident) => {
        impl sealed::Instance for peripherals::$inst {
-            const REGISTERS: *mut bxcan::RegisterBlock = crate::pac::$inst.as_ptr() as *mut _;
            fn regs() -> &'static crate::pac::can::Fdcan {
                &crate::pac::$inst
            }
diff --git a/embassy-stm32/src/can/mod.rs b/embassy-stm32/src/can/mod.rs
index 425f9ac2e..915edb3a6 100644
--- a/embassy-stm32/src/can/mod.rs
+++ b/embassy-stm32/src/can/mod.rs
@@ -1,3 +1,4 @@
+//! Controller Area Network (CAN)
 #![macro_use]
 #[cfg_attr(can_bxcan, path = "bxcan.rs")]
diff --git a/embassy-stm32/src/crc/mod.rs b/embassy-stm32/src/crc/mod.rs
index 63f7ad9ba..29523b92d 100644
--- a/embassy-stm32/src/crc/mod.rs
+++ b/embassy-stm32/src/crc/mod.rs
@@ -1,3 +1,4 @@
+//! Cyclic Redundancy Check (CRC)
 #[cfg_attr(crc_v1, path = "v1.rs")]
 #[cfg_attr(crc_v2, path = "v2v3.rs")]
 #[cfg_attr(crc_v3, path = "v2v3.rs")]
diff --git a/embassy-stm32/src/crc/v1.rs b/embassy-stm32/src/crc/v1.rs
index c0f580830..0166ab819 100644
--- a/embassy-stm32/src/crc/v1.rs
+++ b/embassy-stm32/src/crc/v1.rs
@@ -5,6 +5,7 @@ use crate::peripherals::CRC;
 use crate::rcc::sealed::RccPeripheral;
 use crate::Peripheral;
+/// CRC driver.
 pub struct Crc<'d> {
    _peri: PeripheralRef<'d, CRC>,
 }
@@ -34,6 +35,7 @@ impl<'d> Crc<'d> {
        PAC_CRC.dr().write_value(word);
        self.read()
    }
    /// Feed a slice of words to the peripheral and return the result.
    pub fn feed_words(&mut self, words: &[u32]) -> u32 {
        for word in words {
@@ -42,6 +44,8 @@ impl<'d> Crc<'d> {
        self.read()
    }
+    /// Read the CRC result value.
    pub fn read(&self) -> u32 {
        PAC_CRC.dr().read()
    }
diff --git a/embassy-stm32/src/crc/v2v3.rs b/embassy-stm32/src/crc/v2v3.rs
index b36f6018c..0c4ae55ce 100644
--- a/embassy-stm32/src/crc/v2v3.rs
+++ b/embassy-stm32/src/crc/v2v3.rs
@@ -6,15 +6,19 @@ use crate::peripherals::CRC;
 use crate::rcc::sealed::RccPeripheral;
 use crate::Peripheral;
+/// CRC driver.
 pub struct Crc<'d> {
    _peripheral: PeripheralRef<'d, CRC>,
    _config: Config,
 }
+/// CRC configuration errlr
 pub enum ConfigError {
+    /// The selected polynomial is invalid.
    InvalidPolynomial,
 }
+/// CRC configuration
 pub struct Config {
    reverse_in: InputReverseConfig,
    reverse_out: bool,
@@ -25,14 +29,20 @@ pub struct Config {
    crc_poly: u32,
 }
+/// Input reverse configuration.
 pub enum InputReverseConfig {
+    /// Don't reverse anything
    None,
+    /// Reverse bytes
    Byte,
+    /// Reverse 16-bit halfwords.
    Halfword,
+    /// Reverse 32-bit words.
    Word,
 }
 impl Config {
+    /// Create a new CRC config.
    pub fn new(
        reverse_in: InputReverseConfig,
        reverse_out: bool,
@@ -57,7 +67,9 @@ impl Config {
    }
 }
+/// Polynomial size
 #[cfg(crc_v3)]
+#[allow(missing_docs)]
 pub enum PolySize {
    Width7,
    Width8,
@@ -81,6 +93,7 @@ impl<'d> Crc<'d> {
        instance
    }
+    /// Reset the CRC engine.
    pub fn reset(&mut self) {
        PAC_CRC.cr().modify(|w| w.set_reset(true));
    }
diff --git a/embassy-stm32/src/dac/mod.rs b/embassy-stm32/src/dac/mod.rs
index 500eac4c1..31dedf06e 100644
--- a/embassy-stm32/src/dac/mod.rs
+++ b/embassy-stm32/src/dac/mod.rs
@@ -1,4 +1,4 @@
-//! Provide access to the STM32 digital-to-analog converter (DAC).
+//! Digital to Analog Converter (DAC)
 #![macro_use]
 use core::marker::PhantomData;
@@ -62,11 +62,11 @@ impl Mode {
 ///
 /// 12-bit values outside the permitted range are silently truncated.
 pub enum Value {
-    // 8 bit value
+    /// 8 bit value
    Bit8(u8),
-    // 12 bit value stored in a u16, left-aligned
+    /// 12 bit value stored in a u16, left-aligned
    Bit12Left(u16),
-    // 12 bit value stored in a u16, right-aligned
+    /// 12 bit value stored in a u16, right-aligned
    Bit12Right(u16),
 }
@@ -76,11 +76,11 @@ pub enum Value {
 ///
 /// 12-bit values outside the permitted range are silently truncated.
 pub enum DualValue {
-    // 8 bit value
+    /// 8 bit value
    Bit8(u8, u8),
-    // 12 bit value stored in a u16, left-aligned
+    /// 12 bit value stored in a u16, left-aligned
    Bit12Left(u16, u16),
-    // 12 bit value stored in a u16, right-aligned
+    /// 12 bit value stored in a u16, right-aligned
    Bit12Right(u16, u16),
 }
@@ -88,11 +88,11 @@ pub enum DualValue {
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 /// Array variant of [`Value`].
 pub enum ValueArray<'a> {
-    // 8 bit values
+    /// 8 bit values
    Bit8(&'a [u8]),
-    // 12 bit value stored in a u16, left-aligned
+    /// 12 bit value stored in a u16, left-aligned
    Bit12Left(&'a [u16]),
-    // 12 bit values stored in a u16, right-aligned
+    /// 12 bit values stored in a u16, right-aligned
    Bit12Right(&'a [u16]),
 }
@@ -106,7 +106,9 @@ pub struct DacChannel<'d, T: Instance, const N: u8, DMA = NoDma> {
    dma: PeripheralRef<'d, DMA>,
 }
+/// DAC channel 1 type alias.
 pub type DacCh1<'d, T, DMA = NoDma> = DacChannel<'d, T, 1, DMA>;
+/// DAC channel 2 type alias.
 pub type DacCh2<'d, T, DMA = NoDma> = DacChannel<'d, T, 2, DMA>;
 impl<'d, T: Instance, const N: u8, DMA> DacChannel<'d, T, N, DMA> {
@@ -492,6 +494,7 @@ pub(crate) mod sealed {
    }
 }
+/// DAC instance.
 pub trait Instance: sealed::Instance + RccPeripheral + 'static {}
 dma_trait!(DacDma1, Instance);
 dma_trait!(DacDma2, Instance);
diff --git a/embassy-stm32/src/dac/tsel.rs b/embassy-stm32/src/dac/tsel.rs
index f38dd8fd7..22d8d3dfa 100644
--- a/embassy-stm32/src/dac/tsel.rs
+++ b/embassy-stm32/src/dac/tsel.rs
@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
 /// Trigger selection for STM32F0.
 #[cfg(stm32f0)]
 #[derive(Debug, Copy, Clone, Eq, PartialEq)]
diff --git a/embassy-stm32/src/dcmi.rs b/embassy-stm32/src/dcmi.rs
index b12230794..4d02284b2 100644
--- a/embassy-stm32/src/dcmi.rs
+++ b/embassy-stm32/src/dcmi.rs
@@ -1,3 +1,4 @@
+//! Digital Camera Interface (DCMI)
 use core::future::poll_fn;
 use core::marker::PhantomData;
 use core::task::Poll;
@@ -36,6 +37,7 @@ impl<T: Instance> interrupt::typelevel::Handler<T::Interrupt> for InterruptHandl
 }
 /// The level on the VSync pin when the data is not valid on the parallel interface.
+#[allow(missing_docs)]
 #[derive(Clone, Copy, PartialEq)]
 pub enum VSyncDataInvalidLevel {
    Low,
@@ -43,6 +45,7 @@ pub enum VSyncDataInvalidLevel {
 }
 /// The level on the VSync pin when the data is not valid on the parallel interface.
+#[allow(missing_docs)]
 #[derive(Clone, Copy, PartialEq)]
 pub enum HSyncDataInvalidLevel {
    Low,
@@ -50,14 +53,16 @@ pub enum HSyncDataInvalidLevel {
 }
 #[derive(Clone, Copy, PartialEq)]
+#[allow(missing_docs)]
 pub enum PixelClockPolarity {
    RisingEdge,
    FallingEdge,
 }
-pub struct State {
+struct State {
    waker: AtomicWaker,
 }
 impl State {
    const fn new() -> State {
        State {
@@ -68,18 +73,25 @@ impl State {
 static STATE: State = State::new();
+/// DCMI error.
 #[derive(Debug, Eq, PartialEq, Copy, Clone)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[non_exhaustive]
 pub enum Error {
+    /// Overrun error: the hardware generated data faster than we could read it.
    Overrun,
+    /// Internal peripheral error.
    PeripheralError,
 }
+/// DCMI configuration.
 #[non_exhaustive]
 pub struct Config {
+    /// VSYNC level.
    pub vsync_level: VSyncDataInvalidLevel,
+    /// HSYNC level.
    pub hsync_level: HSyncDataInvalidLevel,
+    /// PIXCLK polarity.
    pub pixclk_polarity: PixelClockPolarity,
 }
@@ -105,6 +117,7 @@ macro_rules! config_pins {
    };
 }
+/// DCMI driver.
 pub struct Dcmi<'d, T: Instance, Dma: FrameDma<T>> {
    inner: PeripheralRef<'d, T>,
    dma: PeripheralRef<'d, Dma>,
@@ -115,6 +128,7 @@ where
    T: Instance,
    Dma: FrameDma<T>,
 {
+    /// Create a new DCMI driver with 8 data bits.
    pub fn new_8bit(
        peri: impl Peripheral<P = T> + 'd,
        dma: impl Peripheral<P = Dma> + 'd,
@@ -139,6 +153,7 @@ where
        Self::new_inner(peri, dma, config, false, 0b00)
    }
+    /// Create a new DCMI driver with 10 data bits.
    pub fn new_10bit(
        peri: impl Peripheral<P = T> + 'd,
        dma: impl Peripheral<P = Dma> + 'd,
@@ -165,6 +180,7 @@ where
        Self::new_inner(peri, dma, config, false, 0b01)
    }
+    /// Create a new DCMI driver with 12 data bits.
    pub fn new_12bit(
        peri: impl Peripheral<P = T> + 'd,
        dma: impl Peripheral<P = Dma> + 'd,
@@ -193,6 +209,7 @@ where
        Self::new_inner(peri, dma, config, false, 0b10)
    }
+    /// Create a new DCMI driver with 14 data bits.
    pub fn new_14bit(
        peri: impl Peripheral<P = T> + 'd,
        dma: impl Peripheral<P = Dma> + 'd,
@@ -223,6 +240,7 @@ where
        Self::new_inner(peri, dma, config, false, 0b11)
    }
+    /// Create a new DCMI driver with 8 data bits, with embedded synchronization.
    pub fn new_es_8bit(
        peri: impl Peripheral<P = T> + 'd,
        dma: impl Peripheral<P = Dma> + 'd,
@@ -245,6 +263,7 @@ where
        Self::new_inner(peri, dma, config, true, 0b00)
    }
+    /// Create a new DCMI driver with 10 data bits, with embedded synchronization.
    pub fn new_es_10bit(
        peri: impl Peripheral<P = T> + 'd,
        dma: impl Peripheral<P = Dma> + 'd,
@@ -269,6 +288,7 @@ where
        Self::new_inner(peri, dma, config, true, 0b01)
    }
+    /// Create a new DCMI driver with 12 data bits, with embedded synchronization.
    pub fn new_es_12bit(
        peri: impl Peripheral<P = T> + 'd,
        dma: impl Peripheral<P = Dma> + 'd,
@@ -295,6 +315,7 @@ where
        Self::new_inner(peri, dma, config, true, 0b10)
    }
+    /// Create a new DCMI driver with 14 data bits, with embedded synchronization.
    pub fn new_es_14bit(
        peri: impl Peripheral<P = T> + 'd,
        dma: impl Peripheral<P = Dma> + 'd,
@@ -538,7 +559,9 @@ mod sealed {
    }
 }
+/// DCMI instance.
 pub trait Instance: sealed::Instance + 'static {
+    /// Interrupt for this instance.
    type Interrupt: interrupt::typelevel::Interrupt;
 }
diff --git a/embassy-stm32/src/dma/bdma.rs b/embassy-stm32/src/dma/bdma.rs
index a7422f66b..a2b83716d 100644
--- a/embassy-stm32/src/dma/bdma.rs
+++ b/embassy-stm32/src/dma/bdma.rs
@@ -1,4 +1,4 @@
-#![macro_use]
+//! Basic Direct Memory Acccess (BDMA)
 use core::future::Future;
 use core::pin::Pin;
@@ -17,11 +17,16 @@ use crate::interrupt::Priority;
 use crate::pac;
 use crate::pac::bdma::{regs, vals};
+/// BDMA transfer options.
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[non_exhaustive]
 pub struct TransferOptions {
    /// Enable circular DMA
+    ///
+    /// Note:
+    /// If you enable circular mode manually, you may want to build and `.await` the `Transfer` in a separate task.
+    /// Since DMA in circular mode need manually stop, `.await` in current task would block the task forever.
    pub circular: bool,
    /// Enable half transfer interrupt
    pub half_transfer_ir: bool,
@@ -140,13 +145,17 @@ pub(crate) unsafe fn on_irq_inner(dma: pac::bdma::Dma, channel_num: usize, index
    STATE.ch_wakers[index].wake();
 }
+/// DMA request type alias.
 #[cfg(any(bdma_v2, dmamux))]
 pub type Request = u8;
+/// DMA request type alias.
 #[cfg(not(any(bdma_v2, dmamux)))]
 pub type Request = ();
+/// DMA channel.
 #[cfg(dmamux)]
 pub trait Channel: sealed::Channel + Peripheral<P = Self> + 'static + super::dmamux::MuxChannel {}
+/// DMA channel.
 #[cfg(not(dmamux))]
 pub trait Channel: sealed::Channel + Peripheral<P = Self> + 'static {}
@@ -161,12 +170,14 @@ pub(crate) mod sealed {
    }
 }
+/// DMA transfer.
 #[must_use = "futures do nothing unless you `.await` or poll them"]
 pub struct Transfer<'a, C: Channel> {
    channel: PeripheralRef<'a, C>,
 }
 impl<'a, C: Channel> Transfer<'a, C> {
+    /// Create a new read DMA transfer (peripheral to memory).
    pub unsafe fn new_read<W: Word>(
        channel: impl Peripheral<P = C> + 'a,
        request: Request,
@@ -177,6 +188,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
        Self::new_read_raw(channel, request, peri_addr, buf, options)
    }
+    /// Create a new read DMA transfer (peripheral to memory), using raw pointers.
    pub unsafe fn new_read_raw<W: Word>(
        channel: impl Peripheral<P = C> + 'a,
        request: Request,
@@ -202,6 +214,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
        )
    }
+    /// Create a new write DMA transfer (memory to peripheral).
    pub unsafe fn new_write<W: Word>(
        channel: impl Peripheral<P = C> + 'a,
        request: Request,
@@ -212,6 +225,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
        Self::new_write_raw(channel, request, buf, peri_addr, options)
    }
+    /// Create a new write DMA transfer (memory to peripheral), using raw pointers.
    pub unsafe fn new_write_raw<W: Word>(
        channel: impl Peripheral<P = C> + 'a,
        request: Request,
@@ -237,6 +251,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
        )
    }
+    /// Create a new write DMA transfer (memory to peripheral), writing the same value repeatedly.
    pub unsafe fn new_write_repeated<W: Word>(
        channel: impl Peripheral<P = C> + 'a,
        request: Request,
@@ -292,20 +307,14 @@ impl<'a, C: Channel> Transfer<'a, C> {
        ch.cr().write(|w| {
            w.set_psize(data_size.into());
            w.set_msize(data_size.into());
-            if incr_mem {
+            w.set_minc(incr_mem);
-                w.set_minc(vals::Inc::ENABLED);
-            } else {
-                w.set_minc(vals::Inc::DISABLED);
-            }
            w.set_dir(dir.into());
            w.set_teie(true);
            w.set_tcie(options.complete_transfer_ir);
            w.set_htie(options.half_transfer_ir);
+            w.set_circ(options.circular);
            if options.circular {
-                w.set_circ(vals::Circ::ENABLED);
                debug!("Setting circular mode");
-            } else {
-                w.set_circ(vals::Circ::DISABLED);
            }
            w.set_pl(vals::Pl::VERYHIGH);
            w.set_en(true);
@@ -321,6 +330,9 @@ impl<'a, C: Channel> Transfer<'a, C> {
        });
    }
+    /// Request the transfer to stop.
+    ///
+    /// This doesn't immediately stop the transfer, you have to wait until [`is_running`](Self::is_running) returns false.
    pub fn request_stop(&mut self) {
        let ch = self.channel.regs().ch(self.channel.num());
@@ -331,21 +343,27 @@ impl<'a, C: Channel> Transfer<'a, C> {
        });
    }
+    /// Return whether this transfer is still running.
+    ///
+    /// If this returns `false`, it can be because either the transfer finished, or
+    /// it was requested to stop early with [`request_stop`](Self::request_stop).
    pub fn is_running(&mut self) -> bool {
        let ch = self.channel.regs().ch(self.channel.num());
        let en = ch.cr().read().en();
-        let circular = ch.cr().read().circ() == vals::Circ::ENABLED;
+        let circular = ch.cr().read().circ();
        let tcif = STATE.complete_count[self.channel.index()].load(Ordering::Acquire) != 0;
        en && (circular || !tcif)
    }
-    /// Gets the total remaining transfers for the channel
+    /// Get the total remaining transfers for the channel.
-    /// Note: this will be zero for transfers that completed without cancellation.
+    ///
+    /// This will be zero for transfers that completed instead of being canceled with [`request_stop`](Self::request_stop).
    pub fn get_remaining_transfers(&self) -> u16 {
        let ch = self.channel.regs().ch(self.channel.num());
        ch.ndtr().read().ndt()
    }
+    /// Blocking wait until the transfer finishes.
    pub fn blocking_wait(mut self) {
        while self.is_running() {}
        self.request_stop();
@@ -411,6 +429,7 @@ impl<'a, C: Channel> DmaCtrl for DmaCtrlImpl<'a, C> {
    }
 }
+/// Ringbuffer for reading data using DMA circular mode.
 pub struct ReadableRingBuffer<'a, C: Channel, W: Word> {
    cr: regs::Cr,
    channel: PeripheralRef<'a, C>,
@@ -418,7 +437,8 @@ pub struct ReadableRingBuffer<'a, C: Channel, W: Word> {
 }
 impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
-    pub unsafe fn new_read(
+    /// Create a new ring buffer.
+    pub unsafe fn new(
        channel: impl Peripheral<P = C> + 'a,
        _request: Request,
        peri_addr: *mut W,
@@ -445,12 +465,12 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
        let mut w = regs::Cr(0);
        w.set_psize(data_size.into());
        w.set_msize(data_size.into());
-        w.set_minc(vals::Inc::ENABLED);
+        w.set_minc(true);
        w.set_dir(dir.into());
        w.set_teie(true);
        w.set_htie(true);
        w.set_tcie(true);
-        w.set_circ(vals::Circ::ENABLED);
+        w.set_circ(true);
        w.set_pl(vals::Pl::VERYHIGH);
        w.set_en(true);
@@ -473,11 +493,15 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
        this
    }
+    /// Start the ring buffer operation.
+    ///
+    /// You must call this after creating it for it to work.
    pub fn start(&mut self) {
        let ch = self.channel.regs().ch(self.channel.num());
        ch.cr().write_value(self.cr)
    }
+    /// Clear all data in the ring buffer.
    pub fn clear(&mut self) {
        self.ringbuf.clear(&mut DmaCtrlImpl(self.channel.reborrow()));
    }
@@ -509,10 +533,11 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
    }
    /// The capacity of the ringbuffer.
-    pub const fn cap(&self) -> usize {
+    pub const fn capacity(&self) -> usize {
        self.ringbuf.cap()
    }
+    /// Set a waker to be woken when at least one byte is received.
    pub fn set_waker(&mut self, waker: &Waker) {
        DmaCtrlImpl(self.channel.reborrow()).set_waker(waker);
    }
@@ -526,6 +551,9 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
        });
    }
+    /// Request DMA to stop.
+    ///
+    /// This doesn't immediately stop the transfer, you have to wait until [`is_running`](Self::is_running) returns false.
    pub fn request_stop(&mut self) {
        let ch = self.channel.regs().ch(self.channel.num());
@@ -539,6 +567,10 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
        });
    }
+    /// Return whether DMA is still running.
+    ///
+    /// If this returns `false`, it can be because either the transfer finished, or
+    /// it was requested to stop early with [`request_stop`](Self::request_stop).
    pub fn is_running(&mut self) -> bool {
        let ch = self.channel.regs().ch(self.channel.num());
        ch.cr().read().en()
@@ -555,6 +587,7 @@ impl<'a, C: Channel, W: Word> Drop for ReadableRingBuffer<'a, C, W> {
    }
 }
+/// Ringbuffer for writing data using DMA circular mode.
 pub struct WritableRingBuffer<'a, C: Channel, W: Word> {
    cr: regs::Cr,
    channel: PeripheralRef<'a, C>,
@@ -562,7 +595,8 @@ pub struct WritableRingBuffer<'a, C: Channel, W: Word> {
 }
 impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
-    pub unsafe fn new_write(
+    /// Create a new ring buffer.
+    pub unsafe fn new(
        channel: impl Peripheral<P = C> + 'a,
        _request: Request,
        peri_addr: *mut W,
@@ -589,12 +623,12 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
        let mut w = regs::Cr(0);
        w.set_psize(data_size.into());
        w.set_msize(data_size.into());
-        w.set_minc(vals::Inc::ENABLED);
+        w.set_minc(true);
        w.set_dir(dir.into());
        w.set_teie(true);
        w.set_htie(true);
        w.set_tcie(true);
-        w.set_circ(vals::Circ::ENABLED);
+        w.set_circ(true);
        w.set_pl(vals::Pl::VERYHIGH);
        w.set_en(true);
@@ -617,11 +651,15 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
        this
    }
+    /// Start the ring buffer operation.
+    ///
+    /// You must call this after creating it for it to work.
    pub fn start(&mut self) {
        let ch = self.channel.regs().ch(self.channel.num());
        ch.cr().write_value(self.cr)
    }
+    /// Clear all data in the ring buffer.
    pub fn clear(&mut self) {
        self.ringbuf.clear(&mut DmaCtrlImpl(self.channel.reborrow()));
    }
@@ -640,10 +678,11 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
    }
    /// The capacity of the ringbuffer.
-    pub const fn cap(&self) -> usize {
+    pub const fn capacity(&self) -> usize {
        self.ringbuf.cap()
    }
+    /// Set a waker to be woken when at least one byte is sent.
    pub fn set_waker(&mut self, waker: &Waker) {
        DmaCtrlImpl(self.channel.reborrow()).set_waker(waker);
    }
@@ -657,6 +696,9 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
        });
    }
+    /// Request DMA to stop.
+    ///
+    /// This doesn't immediately stop the transfer, you have to wait until [`is_running`](Self::is_running) returns false.
    pub fn request_stop(&mut self) {
        let ch = self.channel.regs().ch(self.channel.num());
@@ -670,6 +712,10 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
        });
    }
+    /// Return whether DMA is still running.
+    ///
+    /// If this returns `false`, it can be because either the transfer finished, or
+    /// it was requested to stop early with [`request_stop`](Self::request_stop).
    pub fn is_running(&mut self) -> bool {
        let ch = self.channel.regs().ch(self.channel.num());
        ch.cr().read().en()
diff --git a/embassy-stm32/src/dma/dma.rs b/embassy-stm32/src/dma/dma.rs
index cce0407c1..16d02f273 100644
--- a/embassy-stm32/src/dma/dma.rs
+++ b/embassy-stm32/src/dma/dma.rs
@@ -16,6 +16,7 @@ use crate::interrupt::Priority;
 use crate::pac::dma::{regs, vals};
 use crate::{interrupt, pac};
+/// DMA transfer options.
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[non_exhaustive]
@@ -29,6 +30,10 @@ pub struct TransferOptions {
    /// FIFO threshold for DMA FIFO mode. If none, direct mode is used.
    pub fifo_threshold: Option<FifoThreshold>,
    /// Enable circular DMA
+    ///
+    /// Note:
+    /// If you enable circular mode manually, you may want to build and `.await` the `Transfer` in a separate task.
+    /// Since DMA in circular mode need manually stop, `.await` in current task would block the task forever.
    pub circular: bool,
    /// Enable half transfer interrupt
    pub half_transfer_ir: bool,
@@ -69,6 +74,7 @@ impl From<Dir> for vals::Dir {
    }
 }
+/// DMA transfer burst setting.
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Burst {
@@ -93,6 +99,7 @@ impl From<Burst> for vals::Burst {
    }
 }
+/// DMA flow control setting.
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum FlowControl {
@@ -111,6 +118,7 @@ impl From<FlowControl> for vals::Pfctrl {
    }
 }
+/// DMA FIFO threshold.
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum FifoThreshold {
@@ -208,13 +216,17 @@ pub(crate) unsafe fn on_irq_inner(dma: pac::dma::Dma, channel_num: usize, index:
    STATE.ch_wakers[index].wake();
 }
+/// DMA request type alias. (also known as DMA channel number in some chips)
 #[cfg(any(dma_v2, dmamux))]
 pub type Request = u8;
+/// DMA request type alias. (also known as DMA channel number in some chips)
 #[cfg(not(any(dma_v2, dmamux)))]
 pub type Request = ();
+/// DMA channel.
 #[cfg(dmamux)]
 pub trait Channel: sealed::Channel + Peripheral<P = Self> + 'static + super::dmamux::MuxChannel {}
+/// DMA channel.
 #[cfg(not(dmamux))]
 pub trait Channel: sealed::Channel + Peripheral<P = Self> + 'static {}
@@ -229,12 +241,14 @@ pub(crate) mod sealed {
    }
 }
+/// DMA transfer.
 #[must_use = "futures do nothing unless you `.await` or poll them"]
 pub struct Transfer<'a, C: Channel> {
    channel: PeripheralRef<'a, C>,
 }
 impl<'a, C: Channel> Transfer<'a, C> {
+    /// Create a new read DMA transfer (peripheral to memory).
    pub unsafe fn new_read<W: Word>(
        channel: impl Peripheral<P = C> + 'a,
        request: Request,
@@ -245,6 +259,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
        Self::new_read_raw(channel, request, peri_addr, buf, options)
    }
+    /// Create a new read DMA transfer (peripheral to memory), using raw pointers.
    pub unsafe fn new_read_raw<W: Word>(
        channel: impl Peripheral<P = C> + 'a,
        request: Request,
@@ -270,6 +285,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
        )
    }
+    /// Create a new write DMA transfer (memory to peripheral).
    pub unsafe fn new_write<W: Word>(
        channel: impl Peripheral<P = C> + 'a,
        request: Request,
@@ -280,6 +296,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
        Self::new_write_raw(channel, request, buf, peri_addr, options)
    }
+    /// Create a new write DMA transfer (memory to peripheral), using raw pointers.
    pub unsafe fn new_write_raw<W: Word>(
        channel: impl Peripheral<P = C> + 'a,
        request: Request,
@@ -305,6 +322,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
        )
    }
+    /// Create a new write DMA transfer (memory to peripheral), writing the same value repeatedly.
    pub unsafe fn new_write_repeated<W: Word>(
        channel: impl Peripheral<P = C> + 'a,
        request: Request,
@@ -368,18 +386,13 @@ impl<'a, C: Channel> Transfer<'a, C> {
            w.set_msize(data_size.into());
            w.set_psize(data_size.into());
            w.set_pl(vals::Pl::VERYHIGH);
-            w.set_minc(match incr_mem {
+            w.set_minc(incr_mem);
-                true => vals::Inc::INCREMENTED,
+            w.set_pinc(false);
-                false => vals::Inc::FIXED,
-            });
-            w.set_pinc(vals::Inc::FIXED);
            w.set_teie(true);
            w.set_tcie(options.complete_transfer_ir);
+            w.set_circ(options.circular);
            if options.circular {
-                w.set_circ(vals::Circ::ENABLED);
                debug!("Setting circular mode");
-            } else {
-                w.set_circ(vals::Circ::DISABLED);
            }
            #[cfg(dma_v1)]
            w.set_trbuff(true);
@@ -407,6 +420,9 @@ impl<'a, C: Channel> Transfer<'a, C> {
        });
    }
+    /// Request the transfer to stop.
+    ///
+    /// This doesn't immediately stop the transfer, you have to wait until [`is_running`](Self::is_running) returns false.
    pub fn request_stop(&mut self) {
        let ch = self.channel.regs().st(self.channel.num());
@@ -417,6 +433,10 @@ impl<'a, C: Channel> Transfer<'a, C> {
        });
    }
+    /// Return whether this transfer is still running.
+    ///
+    /// If this returns `false`, it can be because either the transfer finished, or
+    /// it was requested to stop early with [`request_stop`](Self::request_stop).
    pub fn is_running(&mut self) -> bool {
        let ch = self.channel.regs().st(self.channel.num());
        ch.cr().read().en()
@@ -429,6 +449,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
        ch.ndtr().read().ndt()
    }
+    /// Blocking wait until the transfer finishes.
    pub fn blocking_wait(mut self) {
        while self.is_running() {}
@@ -465,12 +486,14 @@ impl<'a, C: Channel> Future for Transfer<'a, C> {
 // ==================================
+/// Double-buffered DMA transfer.
 pub struct DoubleBuffered<'a, C: Channel, W: Word> {
    channel: PeripheralRef<'a, C>,
    _phantom: PhantomData<W>,
 }
 impl<'a, C: Channel, W: Word> DoubleBuffered<'a, C, W> {
+    /// Create a new read DMA transfer (peripheral to memory).
    pub unsafe fn new_read(
        channel: impl Peripheral<P = C> + 'a,
        _request: Request,
@@ -521,8 +544,8 @@ impl<'a, C: Channel, W: Word> DoubleBuffered<'a, C, W> {
            w.set_msize(data_size.into());
            w.set_psize(data_size.into());
            w.set_pl(vals::Pl::VERYHIGH);
-            w.set_minc(vals::Inc::INCREMENTED);
+            w.set_minc(true);
-            w.set_pinc(vals::Inc::FIXED);
+            w.set_pinc(false);
            w.set_teie(true);
            w.set_tcie(true);
            #[cfg(dma_v1)]
@@ -554,25 +577,36 @@ impl<'a, C: Channel, W: Word> DoubleBuffered<'a, C, W> {
        });
    }
+    /// Set the first buffer address.
+    ///
+    /// You may call this while DMA is transferring the other buffer.
    pub unsafe fn set_buffer0(&mut self, buffer: *mut W) {
        let ch = self.channel.regs().st(self.channel.num());
        ch.m0ar().write_value(buffer as _);
    }
+    /// Set the second buffer address.
+    ///
+    /// You may call this while DMA is transferring the other buffer.
    pub unsafe fn set_buffer1(&mut self, buffer: *mut W) {
        let ch = self.channel.regs().st(self.channel.num());
        ch.m1ar().write_value(buffer as _);
    }
+    /// Returh whether buffer0 is accessible (i.e. whether DMA is transferring buffer1 now)
    pub fn is_buffer0_accessible(&mut self) -> bool {
        let ch = self.channel.regs().st(self.channel.num());
        ch.cr().read().ct() == vals::Ct::MEMORY1
    }
+    /// Set a waker to be woken when one of the buffers is being transferred.
    pub fn set_waker(&mut self, waker: &Waker) {
        STATE.ch_wakers[self.channel.index()].register(waker);
    }
+    /// Request the transfer to stop.
+    ///
+    /// This doesn't immediately stop the transfer, you have to wait until [`is_running`](Self::is_running) returns false.
    pub fn request_stop(&mut self) {
        let ch = self.channel.regs().st(self.channel.num());
@@ -583,6 +617,10 @@ impl<'a, C: Channel, W: Word> DoubleBuffered<'a, C, W> {
        });
    }
+    /// Return whether this transfer is still running.
+    ///
+    /// If this returns `false`, it can be because either the transfer finished, or
+    /// it was requested to stop early with [`request_stop`](Self::request_stop).
    pub fn is_running(&mut self) -> bool {
        let ch = self.channel.regs().st(self.channel.num());
        ch.cr().read().en()
@@ -629,6 +667,7 @@ impl<'a, C: Channel> DmaCtrl for DmaCtrlImpl<'a, C> {
    }
 }
+/// Ringbuffer for receiving data using DMA circular mode.
 pub struct ReadableRingBuffer<'a, C: Channel, W: Word> {
    cr: regs::Cr,
    channel: PeripheralRef<'a, C>,
@@ -636,7 +675,8 @@ pub struct ReadableRingBuffer<'a, C: Channel, W: Word> {
 }
 impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
-    pub unsafe fn new_read(
+    /// Create a new ring buffer.
+    pub unsafe fn new(
        channel: impl Peripheral<P = C> + 'a,
        _request: Request,
        peri_addr: *mut W,
@@ -662,12 +702,12 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
        w.set_msize(data_size.into());
        w.set_psize(data_size.into());
        w.set_pl(vals::Pl::VERYHIGH);
-        w.set_minc(vals::Inc::INCREMENTED);
+        w.set_minc(true);
-        w.set_pinc(vals::Inc::FIXED);
+        w.set_pinc(false);
        w.set_teie(true);
        w.set_htie(options.half_transfer_ir);
        w.set_tcie(true);
-        w.set_circ(vals::Circ::ENABLED);
+        w.set_circ(true);
        #[cfg(dma_v1)]
        w.set_trbuff(true);
        #[cfg(dma_v2)]
@@ -706,11 +746,15 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
        this
    }
+    /// Start the ring buffer operation.
+    ///
+    /// You must call this after creating it for it to work.
    pub fn start(&mut self) {
        let ch = self.channel.regs().st(self.channel.num());
        ch.cr().write_value(self.cr);
    }
+    /// Clear all data in the ring buffer.
    pub fn clear(&mut self) {
        self.ringbuf.clear(&mut DmaCtrlImpl(self.channel.reborrow()));
    }
@@ -741,11 +785,12 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
            .await
    }
-    // The capacity of the ringbuffer
+    /// The capacity of the ringbuffer
-    pub const fn cap(&self) -> usize {
+    pub const fn capacity(&self) -> usize {
        self.ringbuf.cap()
    }
+    /// Set a waker to be woken when at least one byte is received.
    pub fn set_waker(&mut self, waker: &Waker) {
        DmaCtrlImpl(self.channel.reborrow()).set_waker(waker);
    }
@@ -763,6 +808,9 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
        });
    }
+    /// Request DMA to stop.
+    ///
+    /// This doesn't immediately stop the transfer, you have to wait until [`is_running`](Self::is_running) returns false.
    pub fn request_stop(&mut self) {
        let ch = self.channel.regs().st(self.channel.num());
@@ -774,6 +822,10 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
        });
    }
+    /// Return whether DMA is still running.
+    ///
+    /// If this returns `false`, it can be because either the transfer finished, or
+    /// it was requested to stop early with [`request_stop`](Self::request_stop).
    pub fn is_running(&mut self) -> bool {
        let ch = self.channel.regs().st(self.channel.num());
        ch.cr().read().en()
@@ -790,6 +842,7 @@ impl<'a, C: Channel, W: Word> Drop for ReadableRingBuffer<'a, C, W> {
    }
 }
+/// Ringbuffer for writing data using DMA circular mode.
 pub struct WritableRingBuffer<'a, C: Channel, W: Word> {
    cr: regs::Cr,
    channel: PeripheralRef<'a, C>,
@@ -797,7 +850,8 @@ pub struct WritableRingBuffer<'a, C: Channel, W: Word> {
 }
 impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
-    pub unsafe fn new_write(
+    /// Create a new ring buffer.
+    pub unsafe fn new(
        channel: impl Peripheral<P = C> + 'a,
        _request: Request,
        peri_addr: *mut W,
@@ -823,12 +877,12 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
        w.set_msize(data_size.into());
        w.set_psize(data_size.into());
        w.set_pl(vals::Pl::VERYHIGH);
-        w.set_minc(vals::Inc::INCREMENTED);
+        w.set_minc(true);
-        w.set_pinc(vals::Inc::FIXED);
+        w.set_pinc(false);
        w.set_teie(true);
        w.set_htie(options.half_transfer_ir);
        w.set_tcie(true);
-        w.set_circ(vals::Circ::ENABLED);
+        w.set_circ(true);
        #[cfg(dma_v1)]
        w.set_trbuff(true);
        #[cfg(dma_v2)]
@@ -867,11 +921,15 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
        this
    }
+    /// Start the ring buffer operation.
+    ///
+    /// You must call this after creating it for it to work.
    pub fn start(&mut self) {
        let ch = self.channel.regs().st(self.channel.num());
        ch.cr().write_value(self.cr);
    }
+    /// Clear all data in the ring buffer.
    pub fn clear(&mut self) {
        self.ringbuf.clear(&mut DmaCtrlImpl(self.channel.reborrow()));
    }
@@ -889,11 +947,12 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
            .await
    }
-    // The capacity of the ringbuffer
+    /// The capacity of the ringbuffer
-    pub const fn cap(&self) -> usize {
+    pub const fn capacity(&self) -> usize {
        self.ringbuf.cap()
    }
+    /// Set a waker to be woken when at least one byte is received.
    pub fn set_waker(&mut self, waker: &Waker) {
        DmaCtrlImpl(self.channel.reborrow()).set_waker(waker);
    }
@@ -911,6 +970,9 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
        });
    }
+    /// Request DMA to stop.
+    ///
+    /// This doesn't immediately stop the transfer, you have to wait until [`is_running`](Self::is_running) returns false.
    pub fn request_stop(&mut self) {
        let ch = self.channel.regs().st(self.channel.num());
@@ -922,6 +984,10 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
        });
    }
+    /// Return whether DMA is still running.
+    ///
+    /// If this returns `false`, it can be because either the transfer finished, or
+    /// it was requested to stop early with [`request_stop`](Self::request_stop).
    pub fn is_running(&mut self) -> bool {
        let ch = self.channel.regs().st(self.channel.num());
        ch.cr().read().en()
diff --git a/embassy-stm32/src/dma/dmamux.rs b/embassy-stm32/src/dma/dmamux.rs
index 20601dc86..9cd494724 100644
--- a/embassy-stm32/src/dma/dmamux.rs
+++ b/embassy-stm32/src/dma/dmamux.rs
@@ -22,11 +22,15 @@ pub(crate) mod dmamux_sealed {
    }
 }
+/// DMAMUX1 instance.
 pub struct DMAMUX1;
+/// DMAMUX2 instance.
 #[cfg(stm32h7)]
 pub struct DMAMUX2;
+/// DMAMUX channel trait.
 pub trait MuxChannel: dmamux_sealed::MuxChannel {
+    /// DMAMUX instance this channel is on.
    type Mux;
 }
diff --git a/embassy-stm32/src/dma/gpdma.rs b/embassy-stm32/src/dma/gpdma.rs
index b061415eb..34b2426b9 100644
--- a/embassy-stm32/src/dma/gpdma.rs
+++ b/embassy-stm32/src/dma/gpdma.rs
@@ -16,6 +16,7 @@ use crate::interrupt::Priority;
 use crate::pac;
 use crate::pac::gpdma::vals;
+/// GPDMA transfer options.
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[non_exhaustive]
@@ -113,10 +114,13 @@ pub(crate) unsafe fn on_irq_inner(dma: pac::gpdma::Gpdma, channel_num: usize, in
    }
 }
+/// DMA request type alias. (also known as DMA channel number in some chips)
 pub type Request = u8;
+/// DMA channel.
 #[cfg(dmamux)]
 pub trait Channel: sealed::Channel + Peripheral<P = Self> + 'static + super::dmamux::MuxChannel {}
+/// DMA channel.
 #[cfg(not(dmamux))]
 pub trait Channel: sealed::Channel + Peripheral<P = Self> + 'static {}
@@ -131,12 +135,14 @@ pub(crate) mod sealed {
    }
 }
+/// DMA transfer.
 #[must_use = "futures do nothing unless you `.await` or poll them"]
 pub struct Transfer<'a, C: Channel> {
    channel: PeripheralRef<'a, C>,
 }
 impl<'a, C: Channel> Transfer<'a, C> {
+    /// Create a new read DMA transfer (peripheral to memory).
    pub unsafe fn new_read<W: Word>(
        channel: impl Peripheral<P = C> + 'a,
        request: Request,
@@ -147,6 +153,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
        Self::new_read_raw(channel, request, peri_addr, buf, options)
    }
+    /// Create a new read DMA transfer (peripheral to memory), using raw pointers.
    pub unsafe fn new_read_raw<W: Word>(
        channel: impl Peripheral<P = C> + 'a,
        request: Request,
@@ -172,6 +179,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
        )
    }
+    /// Create a new write DMA transfer (memory to peripheral).
    pub unsafe fn new_write<W: Word>(
        channel: impl Peripheral<P = C> + 'a,
        request: Request,
@@ -182,6 +190,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
        Self::new_write_raw(channel, request, buf, peri_addr, options)
    }
+    /// Create a new write DMA transfer (memory to peripheral), using raw pointers.
    pub unsafe fn new_write_raw<W: Word>(
        channel: impl Peripheral<P = C> + 'a,
        request: Request,
@@ -207,6 +216,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
        )
    }
+    /// Create a new write DMA transfer (memory to peripheral), writing the same value repeatedly.
    pub unsafe fn new_write_repeated<W: Word>(
        channel: impl Peripheral<P = C> + 'a,
        request: Request,
@@ -297,6 +307,9 @@ impl<'a, C: Channel> Transfer<'a, C> {
        this
    }
+    /// Request the transfer to stop.
+    ///
+    /// This doesn't immediately stop the transfer, you have to wait until [`is_running`](Self::is_running) returns false.
    pub fn request_stop(&mut self) {
        let ch = self.channel.regs().ch(self.channel.num());
        ch.cr().modify(|w| {
@@ -304,6 +317,10 @@ impl<'a, C: Channel> Transfer<'a, C> {
        })
    }
+    /// Return whether this transfer is still running.
+    ///
+    /// If this returns `false`, it can be because either the transfer finished, or
+    /// it was requested to stop early with [`request_stop`](Self::request_stop).
    pub fn is_running(&mut self) -> bool {
        let ch = self.channel.regs().ch(self.channel.num());
        let sr = ch.sr().read();
@@ -317,6 +334,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
        ch.br1().read().bndt()
    }
+    /// Blocking wait until the transfer finishes.
    pub fn blocking_wait(mut self) {
        while self.is_running() {}
diff --git a/embassy-stm32/src/dma/mod.rs b/embassy-stm32/src/dma/mod.rs
index 29fced8fc..38945ac33 100644
--- a/embassy-stm32/src/dma/mod.rs
+++ b/embassy-stm32/src/dma/mod.rs
@@ -1,3 +1,5 @@
+//! Direct Memory Access (DMA)
 #[cfg(dma)]
 pub(crate) mod dma;
 #[cfg(dma)]
@@ -39,6 +41,13 @@ enum Dir {
    PeripheralToMemory,
 }
+/// "No DMA" placeholder.
+///
+/// You may pass this in place of a real DMA channel when creating a driver
+/// to indicate it should not use DMA.
+///
+/// This often causes async functionality to not be available on the instance,
+/// leaving only blocking functionality.
 pub struct NoDma;
 impl_peripheral!(NoDma);
diff --git a/embassy-stm32/src/dma/word.rs b/embassy-stm32/src/dma/word.rs
index aef6e9700..a72c4b7d9 100644
--- a/embassy-stm32/src/dma/word.rs
+++ b/embassy-stm32/src/dma/word.rs
@@ -1,3 +1,6 @@
+//! DMA word sizes.
+#[allow(missing_docs)]
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum WordSize {
@@ -7,6 +10,7 @@ pub enum WordSize {
 }
 impl WordSize {
+    /// Amount of bytes of this word size.
    pub fn bytes(&self) -> usize {
        match self {
            Self::OneByte => 1,
@@ -20,8 +24,13 @@ mod sealed {
    pub trait Word {}
 }
+/// DMA word trait.
+///
+/// This is implemented for u8, u16, u32, etc.
 pub trait Word: sealed::Word + Default + Copy + 'static {
+    /// Word size
    fn size() -> WordSize;
+    /// Amount of bits of this word size.
    fn bits() -> usize;
 }
@@ -40,6 +49,7 @@ macro_rules! impl_word {
    ($T:ident, $uX:ident, $bits:literal, $size:ident) => {
        #[repr(transparent)]
        #[derive(Copy, Clone, Default)]
+        #[doc = concat!(stringify!($T), " word size")]
        pub struct $T(pub $uX);
        impl_word!(_, $T, $bits, $size);
    };
diff --git a/embassy-stm32/src/eth/generic_smi.rs b/embassy-stm32/src/eth/generic_smi.rs
index 1e1094a1c..9c26e90f1 100644
--- a/embassy-stm32/src/eth/generic_smi.rs
+++ b/embassy-stm32/src/eth/generic_smi.rs
@@ -102,6 +102,7 @@ unsafe impl PHY for GenericSMI {
 /// Public functions for the PHY
 impl GenericSMI {
+    /// Set the SMI polling interval.
    #[cfg(feature = "time")]
    pub fn set_poll_interval(&mut self, poll_interval: Duration) {
        self.poll_interval = poll_interval
diff --git a/embassy-stm32/src/eth/mod.rs b/embassy-stm32/src/eth/mod.rs
index 556aadd73..448405507 100644
--- a/embassy-stm32/src/eth/mod.rs
+++ b/embassy-stm32/src/eth/mod.rs
@@ -1,3 +1,4 @@
+//! Ethernet (ETH)
 #![macro_use]
 #[cfg_attr(any(eth_v1a, eth_v1b, eth_v1c), path = "v1/mod.rs")]
@@ -22,6 +23,14 @@ const RX_BUFFER_SIZE: usize = 1536;
 #[derive(Copy, Clone)]
 pub(crate) struct Packet<const N: usize>([u8; N]);
+/// Ethernet packet queue.
+///
+/// This struct owns the memory used for reading and writing packets.
+///
+/// `TX` is the number of packets in the transmit queue, `RX` in the receive
+/// queue. A bigger queue allows the hardware to receive more packets while the
+/// CPU is busy doing other things, which may increase performance (especially for RX)
+/// at the cost of more RAM usage.
 pub struct PacketQueue<const TX: usize, const RX: usize> {
    tx_desc: [TDes; TX],
    rx_desc: [RDes; RX],
@@ -30,6 +39,7 @@ pub struct PacketQueue<const TX: usize, const RX: usize> {
 }
 impl<const TX: usize, const RX: usize> PacketQueue<TX, RX> {
+    /// Create a new packet queue.
    pub const fn new() -> Self {
        const NEW_TDES: TDes = TDes::new();
        const NEW_RDES: RDes = RDes::new();
@@ -41,7 +51,18 @@ impl<const TX: usize, const RX: usize> PacketQueue<TX, RX> {
        }
    }
-    // Allow to initialize a Self without requiring it to go on the stack
+    /// Initialize a packet queue in-place.
+    ///
+    /// This can be helpful to avoid accidentally stack-allocating the packet queue in the stack. The
+    /// Rust compiler can sometimes be a bit dumb when working with large owned values: if you call `new()`
+    /// and then store the returned PacketQueue in its final place (like a `static`), the compiler might
+    /// place it temporarily on the stack then move it. Since this struct is quite big, it may result
+    /// in a stack overflow.
+    ///
+    /// With this function, you can create an uninitialized `static` with type `MaybeUninit<PacketQueue<...>>`
+    /// and initialize it in-place, guaranteeing no stack usage.
+    ///
+    /// After calling this function, calling `assume_init` on the MaybeUninit is guaranteed safe.
    pub fn init(this: &mut MaybeUninit<Self>) {
        unsafe {
            this.as_mut_ptr().write_bytes(0u8, 1);
@@ -93,6 +114,7 @@ impl<'d, T: Instance, P: PHY> embassy_net_driver::Driver for Ethernet<'d, T, P>
    }
 }
+/// `embassy-net` RX token.
 pub struct RxToken<'a, 'd> {
    rx: &'a mut RDesRing<'d>,
 }
@@ -110,6 +132,7 @@ impl<'a, 'd> embassy_net_driver::RxToken for RxToken<'a, 'd> {
    }
 }
+/// `embassy-net` TX token.
 pub struct TxToken<'a, 'd> {
    tx: &'a mut TDesRing<'d>,
 }
@@ -159,6 +182,7 @@ pub(crate) mod sealed {
    }
 }
+/// Ethernet instance.
 pub trait Instance: sealed::Instance + Send + 'static {}
 impl sealed::Instance for crate::peripherals::ETH {
diff --git a/embassy-stm32/src/eth/v1/mod.rs b/embassy-stm32/src/eth/v1/mod.rs
index 13e53f687..2ce5b3927 100644
--- a/embassy-stm32/src/eth/v1/mod.rs
+++ b/embassy-stm32/src/eth/v1/mod.rs
@@ -43,6 +43,7 @@ impl interrupt::typelevel::Handler<interrupt::typelevel::ETH> for InterruptHandl
    }
 }
+/// Ethernet driver.
 pub struct Ethernet<'d, T: Instance, P: PHY> {
    _peri: PeripheralRef<'d, T>,
    pub(crate) tx: TDesRing<'d>,
@@ -266,6 +267,7 @@ impl<'d, T: Instance, P: PHY> Ethernet<'d, T, P> {
    }
 }
+/// Ethernet station management interface.
 pub struct EthernetStationManagement<T: Instance> {
    peri: PhantomData<T>,
    clock_range: Cr,
diff --git a/embassy-stm32/src/eth/v2/mod.rs b/embassy-stm32/src/eth/v2/mod.rs
index c77155fea..59745cba0 100644
--- a/embassy-stm32/src/eth/v2/mod.rs
+++ b/embassy-stm32/src/eth/v2/mod.rs
@@ -34,6 +34,7 @@ impl interrupt::typelevel::Handler<interrupt::typelevel::ETH> for InterruptHandl
    }
 }
+/// Ethernet driver.
 pub struct Ethernet<'d, T: Instance, P: PHY> {
    _peri: PeripheralRef<'d, T>,
    pub(crate) tx: TDesRing<'d>,
@@ -56,6 +57,7 @@ macro_rules! config_pins {
 }
 impl<'d, T: Instance, P: PHY> Ethernet<'d, T, P> {
+    /// Create a new Ethernet driver.
    pub fn new<const TX: usize, const RX: usize>(
        queue: &'d mut PacketQueue<TX, RX>,
        peri: impl Peripheral<P = T> + 'd,
@@ -237,6 +239,7 @@ impl<'d, T: Instance, P: PHY> Ethernet<'d, T, P> {
    }
 }
+/// Ethernet SMI driver.
 pub struct EthernetStationManagement<T: Instance> {
    peri: PhantomData<T>,
    clock_range: u8,
diff --git a/embassy-stm32/src/exti.rs b/embassy-stm32/src/exti.rs
index dbd24804f..f83bae3ff 100644
--- a/embassy-stm32/src/exti.rs
+++ b/embassy-stm32/src/exti.rs
@@ -1,3 +1,4 @@
+//! External Interrupts (EXTI)
 use core::convert::Infallible;
 use core::future::Future;
 use core::marker::PhantomData;
@@ -39,7 +40,7 @@ fn exticr_regs() -> pac::afio::Afio {
    pac::AFIO
 }
-pub unsafe fn on_irq() {
+unsafe fn on_irq() {
    #[cfg(feature = "low-power")]
    crate::low_power::on_wakeup_irq();
@@ -85,7 +86,13 @@ impl Iterator for BitIter {
    }
 }
-/// EXTI input driver
+/// EXTI input driver.
+///
+/// This driver augments a GPIO `Input` with EXTI functionality. EXTI is not
+/// built into `Input` itself because it needs to take ownership of the corresponding
+/// EXTI channel, which is a limited resource.
+///
+/// Pins PA5, PB5, PC5... all use EXTI channel 5, so you can't use EXTI on, say, PA5 and PC5 at the same time.
 pub struct ExtiInput<'d, T: GpioPin> {
    pin: Input<'d, T>,
 }
@@ -93,23 +100,30 @@ pub struct ExtiInput<'d, T: GpioPin> {
 impl<'d, T: GpioPin> Unpin for ExtiInput<'d, T> {}
 impl<'d, T: GpioPin> ExtiInput<'d, T> {
+    /// Create an EXTI input.
    pub fn new(pin: Input<'d, T>, _ch: impl Peripheral<P = T::ExtiChannel> + 'd) -> Self {
        Self { pin }
    }
-    pub fn is_high(&self) -> bool {
+    /// Get whether the pin is high.
+    pub fn is_high(&mut self) -> bool {
        self.pin.is_high()
    }
-    pub fn is_low(&self) -> bool {
+    /// Get whether the pin is low.
+    pub fn is_low(&mut self) -> bool {
        self.pin.is_low()
    }
-    pub fn get_level(&self) -> Level {
+    /// Get the pin level.
+    pub fn get_level(&mut self) -> Level {
        self.pin.get_level()
    }
-    pub async fn wait_for_high<'a>(&'a mut self) {
+    /// Asynchronously wait until the pin is high.
+    ///
+    /// This returns immediately if the pin is already high.
+    pub async fn wait_for_high(&mut self) {
        let fut = ExtiInputFuture::new(self.pin.pin.pin.pin(), self.pin.pin.pin.port(), true, false);
        if self.is_high() {
            return;
@@ -117,7 +131,10 @@ impl<'d, T: GpioPin> ExtiInput<'d, T> {
        fut.await
    }
-    pub async fn wait_for_low<'a>(&'a mut self) {
+    /// Asynchronously wait until the pin is low.
+    ///
+    /// This returns immediately if the pin is already low.
+    pub async fn wait_for_low(&mut self) {
        let fut = ExtiInputFuture::new(self.pin.pin.pin.pin(), self.pin.pin.pin.port(), false, true);
        if self.is_low() {
            return;
@@ -125,15 +142,22 @@ impl<'d, T: GpioPin> ExtiInput<'d, T> {
        fut.await
    }
-    pub async fn wait_for_rising_edge<'a>(&'a mut self) {
+    /// Asynchronously wait until the pin sees a rising edge.
+    ///
+    /// If the pin is already high, it will wait for it to go low then back high.
+    pub async fn wait_for_rising_edge(&mut self) {
        ExtiInputFuture::new(self.pin.pin.pin.pin(), self.pin.pin.pin.port(), true, false).await
    }
-    pub async fn wait_for_falling_edge<'a>(&'a mut self) {
+    /// Asynchronously wait until the pin sees a falling edge.
+    ///
+    /// If the pin is already low, it will wait for it to go high then back low.
+    pub async fn wait_for_falling_edge(&mut self) {
        ExtiInputFuture::new(self.pin.pin.pin.pin(), self.pin.pin.pin.port(), false, true).await
    }
-    pub async fn wait_for_any_edge<'a>(&'a mut self) {
+    /// Asynchronously wait until the pin sees any edge (either rising or falling).
+    pub async fn wait_for_any_edge(&mut self) {
        ExtiInputFuture::new(self.pin.pin.pin.pin(), self.pin.pin.pin.port(), true, true).await
    }
 }
@@ -142,11 +166,11 @@ impl<'d, T: GpioPin> embedded_hal_02::digital::v2::InputPin for ExtiInput<'d, T>
    type Error = Infallible;
    fn is_high(&self) -> Result<bool, Self::Error> {
-        Ok(self.is_high())
+        Ok(!self.pin.pin.ref_is_low())
    }
    fn is_low(&self) -> Result<bool, Self::Error> {
-        Ok(self.is_low())
+        Ok(self.pin.pin.ref_is_low())
    }
 }
@@ -155,11 +179,11 @@ impl<'d, T: GpioPin> embedded_hal_1::digital::ErrorType for ExtiInput<'d, T> {
 }
 impl<'d, T: GpioPin> embedded_hal_1::digital::InputPin for ExtiInput<'d, T> {
-    fn is_high(&self) -> Result<bool, Self::Error> {
+    fn is_high(&mut self) -> Result<bool, Self::Error> {
        Ok(self.is_high())
    }
-    fn is_low(&self) -> Result<bool, Self::Error> {
+    fn is_low(&mut self) -> Result<bool, Self::Error> {
        Ok(self.is_low())
    }
 }
@@ -284,6 +308,7 @@ macro_rules! foreach_exti_irq {
 macro_rules! impl_irq {
    ($e:ident) => {
+        #[allow(non_snake_case)]
        #[cfg(feature = "rt")]
        #[interrupt]
        unsafe fn $e() {
@@ -298,8 +323,16 @@ pub(crate) mod sealed {
    pub trait Channel {}
 }
+/// EXTI channel trait.
 pub trait Channel: sealed::Channel + Sized {
+    /// Get the EXTI channel number.
    fn number(&self) -> usize;
+    /// Type-erase (degrade) this channel into an `AnyChannel`.
+    ///
+    /// This converts EXTI channel singletons (`EXTI0`, `EXTI1`, ...), which
+    /// are all different types, into the same type. It is useful for
+    /// creating arrays of channels, or avoiding generics.
    fn degrade(self) -> AnyChannel {
        AnyChannel {
            number: self.number() as u8,
@@ -307,9 +340,13 @@ pub trait Channel: sealed::Channel + Sized {
    }
 }
+/// Type-erased (degraded) EXTI channel.
+///
+/// This represents ownership over any EXTI channel, known at runtime.
 pub struct AnyChannel {
    number: u8,
 }
 impl_peripheral!(AnyChannel);
 impl sealed::Channel for AnyChannel {}
 impl Channel for AnyChannel {
diff --git a/embassy-stm32/src/flash/asynch.rs b/embassy-stm32/src/flash/asynch.rs
index eae40c7ec..97eaece81 100644
--- a/embassy-stm32/src/flash/asynch.rs
+++ b/embassy-stm32/src/flash/asynch.rs
@@ -17,6 +17,7 @@ use crate::{interrupt, Peripheral};
 pub(super) static REGION_ACCESS: Mutex<CriticalSectionRawMutex, ()> = Mutex::new(());
 impl<'d> Flash<'d, Async> {
+    /// Create a new flash driver with async capabilities.
    pub fn new(
        p: impl Peripheral<P = FLASH> + 'd,
        _irq: impl interrupt::typelevel::Binding<crate::interrupt::typelevel::FLASH, InterruptHandler> + 'd,
@@ -32,15 +33,26 @@ impl<'d> Flash<'d, Async> {
        }
    }
+    /// Split this flash driver into one instance per flash memory region.
+    ///
+    /// See module-level documentation for details on how memory regions work.
    pub fn into_regions(self) -> FlashLayout<'d, Async> {
        assert!(family::is_default_layout());
        FlashLayout::new(self.inner)
    }
+    /// Async write.
+    ///
+    /// NOTE: `offset` is an offset from the flash start, NOT an absolute address.
+    /// For example, to write address `0x0800_1234` you have to use offset `0x1234`.
    pub async fn write(&mut self, offset: u32, bytes: &[u8]) -> Result<(), Error> {
        unsafe { write_chunked(FLASH_BASE as u32, FLASH_SIZE as u32, offset, bytes).await }
    }
+    /// Async erase.
+    ///
+    /// NOTE: `from` and `to` are offsets from the flash start, NOT an absolute address.
+    /// For example, to erase address `0x0801_0000` you have to use offset `0x1_0000`.
    pub async fn erase(&mut self, from: u32, to: u32) -> Result<(), Error> {
        unsafe { erase_sectored(FLASH_BASE as u32, from, to).await }
    }
@@ -59,7 +71,7 @@ impl embedded_storage_async::nor_flash::ReadNorFlash for Flash<'_, Async> {
    const READ_SIZE: usize = super::READ_SIZE;
    async fn read(&mut self, offset: u32, bytes: &mut [u8]) -> Result<(), Self::Error> {
-        self.read(offset, bytes)
+        self.blocking_read(offset, bytes)
    }
    fn capacity(&self) -> usize {
@@ -141,15 +153,20 @@ pub(super) async unsafe fn erase_sectored(base: u32, from: u32, to: u32) -> Resu
 foreach_flash_region! {
    ($type_name:ident, $write_size:literal, $erase_size:literal) => {
        impl crate::_generated::flash_regions::$type_name<'_, Async> {
+            /// Async read.
+            ///
+            /// Note: reading from flash can't actually block, so this is the same as `blocking_read`.
            pub async fn read(&mut self, offset: u32, bytes: &mut [u8]) -> Result<(), Error> {
                blocking_read(self.0.base, self.0.size, offset, bytes)
            }
+            /// Async write.
            pub async fn write(&mut self, offset: u32, bytes: &[u8]) -> Result<(), Error> {
                let _guard = REGION_ACCESS.lock().await;
                unsafe { write_chunked(self.0.base, self.0.size, offset, bytes).await }
            }
+            /// Async erase.
            pub async fn erase(&mut self, from: u32, to: u32) -> Result<(), Error> {
                let _guard = REGION_ACCESS.lock().await;
                unsafe { erase_sectored(self.0.base, from, to).await }
diff --git a/embassy-stm32/src/flash/common.rs b/embassy-stm32/src/flash/common.rs
index 8acad1c7c..f8561edb3 100644
--- a/embassy-stm32/src/flash/common.rs
+++ b/embassy-stm32/src/flash/common.rs
@@ -12,12 +12,14 @@ use super::{
 use crate::peripherals::FLASH;
 use crate::Peripheral;
+/// Internal flash memory driver.
 pub struct Flash<'d, MODE = Async> {
    pub(crate) inner: PeripheralRef<'d, FLASH>,
    pub(crate) _mode: PhantomData<MODE>,
 }
 impl<'d> Flash<'d, Blocking> {
+    /// Create a new flash driver, usable in blocking mode.
    pub fn new_blocking(p: impl Peripheral<P = FLASH> + 'd) -> Self {
        into_ref!(p);
@@ -29,15 +31,26 @@ impl<'d> Flash<'d, Blocking> {
 }
 impl<'d, MODE> Flash<'d, MODE> {
+    /// Split this flash driver into one instance per flash memory region.
+    ///
+    /// See module-level documentation for details on how memory regions work.
    pub fn into_blocking_regions(self) -> FlashLayout<'d, Blocking> {
        assert!(family::is_default_layout());
        FlashLayout::new(self.inner)
    }
-    pub fn read(&mut self, offset: u32, bytes: &mut [u8]) -> Result<(), Error> {
+    /// Blocking read.
+    ///
+    /// NOTE: `offset` is an offset from the flash start, NOT an absolute address.
+    /// For example, to read address `0x0800_1234` you have to use offset `0x1234`.
+    pub fn blocking_read(&mut self, offset: u32, bytes: &mut [u8]) -> Result<(), Error> {
        blocking_read(FLASH_BASE as u32, FLASH_SIZE as u32, offset, bytes)
    }
+    /// Blocking write.
+    ///
+    /// NOTE: `offset` is an offset from the flash start, NOT an absolute address.
+    /// For example, to write address `0x0800_1234` you have to use offset `0x1234`.
    pub fn blocking_write(&mut self, offset: u32, bytes: &[u8]) -> Result<(), Error> {
        unsafe {
            blocking_write(
@@ -50,6 +63,10 @@ impl<'d, MODE> Flash<'d, MODE> {
        }
    }
+    /// Blocking erase.
+    ///
+    /// NOTE: `from` and `to` are offsets from the flash start, NOT an absolute address.
+    /// For example, to erase address `0x0801_0000` you have to use offset `0x1_0000`.
    pub fn blocking_erase(&mut self, from: u32, to: u32) -> Result<(), Error> {
        unsafe { blocking_erase(FLASH_BASE as u32, from, to, erase_sector_unlocked) }
    }
@@ -206,7 +223,7 @@ impl<MODE> embedded_storage::nor_flash::ReadNorFlash for Flash<'_, MODE> {
    const READ_SIZE: usize = READ_SIZE;
    fn read(&mut self, offset: u32, bytes: &mut [u8]) -> Result<(), Self::Error> {
-        self.read(offset, bytes)
+        self.blocking_read(offset, bytes)
    }
    fn capacity(&self) -> usize {
@@ -230,16 +247,28 @@ impl<MODE> embedded_storage::nor_flash::NorFlash for Flash<'_, MODE> {
 foreach_flash_region! {
    ($type_name:ident, $write_size:literal, $erase_size:literal) => {
        impl<MODE> crate::_generated::flash_regions::$type_name<'_, MODE> {
+            /// Blocking read.
+            ///
+            /// NOTE: `offset` is an offset from the flash start, NOT an absolute address.
+            /// For example, to read address `0x0800_1234` you have to use offset `0x1234`.
            pub fn blocking_read(&mut self, offset: u32, bytes: &mut [u8]) -> Result<(), Error> {
                blocking_read(self.0.base, self.0.size, offset, bytes)
            }
        }
        impl crate::_generated::flash_regions::$type_name<'_, Blocking> {
+            /// Blocking write.
+            ///
+            /// NOTE: `offset` is an offset from the flash start, NOT an absolute address.
+            /// For example, to write address `0x0800_1234` you have to use offset `0x1234`.
            pub fn blocking_write(&mut self, offset: u32, bytes: &[u8]) -> Result<(), Error> {
                unsafe { blocking_write(self.0.base, self.0.size, offset, bytes, write_chunk_with_critical_section) }
            }
+            /// Blocking erase.
+            ///
+            /// NOTE: `from` and `to` are offsets from the flash start, NOT an absolute address.
+            /// For example, to erase address `0x0801_0000` you have to use offset `0x1_0000`.
            pub fn blocking_erase(&mut self, from: u32, to: u32) -> Result<(), Error> {
                unsafe { blocking_erase(self.0.base, from, to, erase_sector_with_critical_section) }
            }
diff --git a/embassy-stm32/src/flash/f0.rs b/embassy-stm32/src/flash/f0.rs
index 1ab8435a0..c0a8d7022 100644
--- a/embassy-stm32/src/flash/f0.rs
+++ b/embassy-stm32/src/flash/f0.rs
@@ -6,11 +6,11 @@ use super::{FlashRegion, FlashSector, FLASH_REGIONS, WRITE_SIZE};
 use crate::flash::Error;
 use crate::pac;
-pub const fn is_default_layout() -> bool {
+pub(crate) const fn is_default_layout() -> bool {
    true
 }
-pub const fn get_flash_regions() -> &'static [&'static FlashRegion] {
+pub(crate) const fn get_flash_regions() -> &'static [&'static FlashRegion] {
    &FLASH_REGIONS
 }
@@ -79,7 +79,7 @@ pub(crate) unsafe fn blocking_erase_sector(sector: &FlashSector) -> Result<(), E
 pub(crate) unsafe fn clear_all_err() {
    // read and write back the same value.
-    // This clears all "write 0 to clear" bits.
+    // This clears all "write 1 to clear" bits.
    pac::FLASH.sr().modify(|_| {});
 }
diff --git a/embassy-stm32/src/flash/f3.rs b/embassy-stm32/src/flash/f3.rs
index 7e6d7ca26..817ccef4d 100644
--- a/embassy-stm32/src/flash/f3.rs
+++ b/embassy-stm32/src/flash/f3.rs
@@ -6,11 +6,11 @@ use super::{FlashRegion, FlashSector, FLASH_REGIONS, WRITE_SIZE};
 use crate::flash::Error;
 use crate::pac;
-pub const fn is_default_layout() -> bool {
+pub(crate) const fn is_default_layout() -> bool {
    true
 }
-pub const fn get_flash_regions() -> &'static [&'static FlashRegion] {
+pub(crate) const fn get_flash_regions() -> &'static [&'static FlashRegion] {
    &FLASH_REGIONS
 }
@@ -79,7 +79,7 @@ pub(crate) unsafe fn blocking_erase_sector(sector: &FlashSector) -> Result<(), E
 pub(crate) unsafe fn clear_all_err() {
    // read and write back the same value.
-    // This clears all "write 0 to clear" bits.
+    // This clears all "write 1 to clear" bits.
    pac::FLASH.sr().modify(|_| {});
 }
diff --git a/embassy-stm32/src/flash/f4.rs b/embassy-stm32/src/flash/f4.rs
index 5d07020ce..2671dfb04 100644
--- a/embassy-stm32/src/flash/f4.rs
+++ b/embassy-stm32/src/flash/f4.rs
@@ -9,7 +9,7 @@ use pac::FLASH_SIZE;
 use super::{FlashBank, FlashRegion, FlashSector, FLASH_REGIONS, WRITE_SIZE};
 use crate::flash::Error;
 use crate::pac;
+#[allow(missing_docs)] // TODO
 #[cfg(any(stm32f427, stm32f429, stm32f437, stm32f439, stm32f469, stm32f479))]
 mod alt_regions {
    use core::marker::PhantomData;
@@ -337,7 +337,7 @@ pub(crate) unsafe fn blocking_erase_sector(sector: &FlashSector) -> Result<(), E
 pub(crate) fn clear_all_err() {
    // read and write back the same value.
-    // This clears all "write 0 to clear" bits.
+    // This clears all "write 1 to clear" bits.
    pac::FLASH.sr().modify(|_| {});
 }
diff --git a/embassy-stm32/src/flash/f7.rs b/embassy-stm32/src/flash/f7.rs
index b52231ca8..6b3e66ac6 100644
--- a/embassy-stm32/src/flash/f7.rs
+++ b/embassy-stm32/src/flash/f7.rs
@@ -6,11 +6,11 @@ use super::{FlashRegion, FlashSector, FLASH_REGIONS, WRITE_SIZE};
 use crate::flash::Error;
 use crate::pac;
-pub const fn is_default_layout() -> bool {
+pub(crate) const fn is_default_layout() -> bool {
    true
 }
-pub const fn get_flash_regions() -> &'static [&'static FlashRegion] {
+pub(crate) const fn get_flash_regions() -> &'static [&'static FlashRegion] {
    &FLASH_REGIONS
 }
@@ -69,7 +69,7 @@ pub(crate) unsafe fn blocking_erase_sector(sector: &FlashSector) -> Result<(), E
 pub(crate) unsafe fn clear_all_err() {
    // read and write back the same value.
-    // This clears all "write 0 to clear" bits.
+    // This clears all "write 1 to clear" bits.
    pac::FLASH.sr().modify(|_| {});
 }
diff --git a/embassy-stm32/src/flash/g0.rs b/embassy-stm32/src/flash/g.rs
index 19a388970..d97b4a932 100644
--- a/embassy-stm32/src/flash/g0.rs
+++ b/embassy-stm32/src/flash/g.rs
@@ -8,11 +8,11 @@ use super::{FlashRegion, FlashSector, FLASH_REGIONS, WRITE_SIZE};
 use crate::flash::Error;
 use crate::pac;
-pub const fn is_default_layout() -> bool {
+pub(crate) const fn is_default_layout() -> bool {
    true
 }
-pub const fn get_flash_regions() -> &'static [&'static FlashRegion] {
+pub(crate) const fn get_flash_regions() -> &'static [&'static FlashRegion] {
    &FLASH_REGIONS
 }
@@ -92,6 +92,6 @@ pub(crate) unsafe fn wait_ready_blocking() -> Result<(), Error> {
 pub(crate) unsafe fn clear_all_err() {
    // read and write back the same value.
-    // This clears all "write 0 to clear" bits.
+    // This clears all "write 1 to clear" bits.
    pac::FLASH.sr().modify(|_| {});
 }
diff --git a/embassy-stm32/src/flash/h7.rs b/embassy-stm32/src/flash/h7.rs
index b064fd6ea..65d163d29 100644
--- a/embassy-stm32/src/flash/h7.rs
+++ b/embassy-stm32/src/flash/h7.rs
@@ -6,7 +6,7 @@ use super::{FlashRegion, FlashSector, BANK1_REGION, FLASH_REGIONS, WRITE_SIZE};
 use crate::flash::Error;
 use crate::pac;
-pub const fn is_default_layout() -> bool {
+pub(crate) const fn is_default_layout() -> bool {
    true
 }
@@ -14,7 +14,7 @@ const fn is_dual_bank() -> bool {
    FLASH_REGIONS.len() >= 2
 }
-pub fn get_flash_regions() -> &'static [&'static FlashRegion] {
+pub(crate) fn get_flash_regions() -> &'static [&'static FlashRegion] {
    &FLASH_REGIONS
 }
@@ -113,7 +113,7 @@ pub(crate) unsafe fn clear_all_err() {
 unsafe fn bank_clear_all_err(bank: pac::flash::Bank) {
    // read and write back the same value.
-    // This clears all "write 0 to clear" bits.
+    // This clears all "write 1 to clear" bits.
    bank.sr().modify(|_| {});
 }
diff --git a/embassy-stm32/src/flash/l.rs b/embassy-stm32/src/flash/l.rs
index 1db0da923..0b332dc61 100644
--- a/embassy-stm32/src/flash/l.rs
+++ b/embassy-stm32/src/flash/l.rs
@@ -5,11 +5,11 @@ use super::{FlashRegion, FlashSector, FLASH_REGIONS, WRITE_SIZE};
 use crate::flash::Error;
 use crate::pac;
-pub const fn is_default_layout() -> bool {
+pub(crate) const fn is_default_layout() -> bool {
    true
 }
-pub const fn get_flash_regions() -> &'static [&'static FlashRegion] {
+pub(crate) const fn get_flash_regions() -> &'static [&'static FlashRegion] {
    &FLASH_REGIONS
 }
@@ -120,7 +120,7 @@ pub(crate) unsafe fn blocking_erase_sector(sector: &FlashSector) -> Result<(), E
 pub(crate) unsafe fn clear_all_err() {
    // read and write back the same value.
-    // This clears all "write 0 to clear" bits.
+    // This clears all "write 1 to clear" bits.
    pac::FLASH.sr().modify(|_| {});
 }
diff --git a/embassy-stm32/src/flash/mod.rs b/embassy-stm32/src/flash/mod.rs
index fb20dcd38..cbf5c25b2 100644
--- a/embassy-stm32/src/flash/mod.rs
+++ b/embassy-stm32/src/flash/mod.rs
@@ -1,3 +1,4 @@
+//! Flash memory (FLASH)
 use embedded_storage::nor_flash::{NorFlashError, NorFlashErrorKind};
 #[cfg(flash_f4)]
@@ -14,62 +15,96 @@ 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;
+/// Blocking flash mode typestate.
-pub struct Async;
+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: (),
 }
+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,
 }
-impl FlashRegion {
-    pub const fn end(&self) -> u32 {
-        self.base + self.size
-    }
-    pub const fn sectors(&self) -> u8 {
-        (self.size / self.erase_size) as u8
-    }
-}
 #[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")]
 #[cfg_attr(flash_f4, path = "f4.rs")]
 #[cfg_attr(flash_f7, path = "f7.rs")]
-#[cfg_attr(flash_g0, path = "g0.rs")]
+#[cfg_attr(any(flash_g0, flash_g4), path = "g.rs")]
 #[cfg_attr(flash_h7, path = "h7.rs")]
 #[cfg_attr(flash_h7ab, path = "h7.rs")]
 #[cfg_attr(
    not(any(
-        flash_l0, flash_l1, flash_l4, flash_wl, flash_wb, flash_f0, flash_f3, flash_f4, flash_f7, flash_g0, flash_h7,
+        flash_l0, flash_l1, flash_l4, flash_wl, flash_wb, flash_f0, flash_f3, flash_f4, flash_f7, flash_g0, flash_g4,
-        flash_h7ab
+        flash_h7, flash_h7ab
    )),
    path = "other.rs"
 )]
@@ -78,6 +113,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 {
diff --git a/embassy-stm32/src/flash/other.rs b/embassy-stm32/src/flash/other.rs
index a7e8d1d57..20f84a72f 100644
--- a/embassy-stm32/src/flash/other.rs
+++ b/embassy-stm32/src/flash/other.rs
@@ -2,11 +2,11 @@
 use super::{Error, FlashRegion, FlashSector, FLASH_REGIONS, WRITE_SIZE};
-pub const fn is_default_layout() -> bool {
+pub(crate) const fn is_default_layout() -> bool {
    true
 }
-pub const fn get_flash_regions() -> &'static [&'static FlashRegion] {
+pub(crate) const fn get_flash_regions() -> &'static [&'static FlashRegion] {
    &FLASH_REGIONS
 }
diff --git a/embassy-stm32/src/fmc.rs b/embassy-stm32/src/fmc.rs
index dd0d27217..873c8a70c 100644
--- a/embassy-stm32/src/fmc.rs
+++ b/embassy-stm32/src/fmc.rs
@@ -1,3 +1,4 @@
+//! Flexible Memory Controller (FMC) / Flexible Static Memory Controller (FSMC)
 use core::marker::PhantomData;
 use embassy_hal_internal::into_ref;
@@ -6,6 +7,7 @@ use crate::gpio::sealed::AFType;
 use crate::gpio::{Pull, Speed};
 use crate::Peripheral;
+/// FMC driver
 pub struct Fmc<'d, T: Instance> {
    peri: PhantomData<&'d mut T>,
 }
@@ -38,6 +40,7 @@ where
        T::REGS.bcr1().modify(|r| r.set_fmcen(true));
    }
+    /// Get the kernel clock currently in use for this FMC instance.
    pub fn source_clock_hz(&self) -> u32 {
        <T as crate::rcc::sealed::RccPeripheral>::frequency().0
    }
@@ -85,6 +88,7 @@ macro_rules! fmc_sdram_constructor {
        nbl: [$(($nbl_pin_name:ident: $nbl_signal:ident)),*],
        ctrl: [$(($ctrl_pin_name:ident: $ctrl_signal:ident)),*]
    )) => {
+        /// Create a new FMC instance.
        pub fn $name<CHIP: stm32_fmc::SdramChip>(
            _instance: impl Peripheral<P = T> + 'd,
            $($addr_pin_name: impl Peripheral<P = impl $addr_signal<T>> + 'd),*,
@@ -199,6 +203,7 @@ pub(crate) mod sealed {
    }
 }
+/// FMC instance trait.
 pub trait Instance: sealed::Instance + 'static {}
 foreach_peripheral!(
diff --git a/embassy-stm32/src/gpio.rs b/embassy-stm32/src/gpio.rs
index b863c4ffe..c300a079e 100644
--- a/embassy-stm32/src/gpio.rs
+++ b/embassy-stm32/src/gpio.rs
@@ -1,3 +1,5 @@
+//! General-purpose Input/Output (GPIO)
 #![macro_use]
 use core::convert::Infallible;
@@ -29,6 +31,11 @@ impl<'d, T: Pin> Flex<'d, T> {
        Self { pin }
    }
+    /// Type-erase (degrade) this pin into an `AnyPin`.
+    ///
+    /// This converts pin singletons (`PA5`, `PB6`, ...), which
+    /// are all different types, into the same type. It is useful for
+    /// creating arrays of pins, or avoiding generics.
    #[inline]
    pub fn degrade(self) -> Flex<'d, AnyPin> {
        // Safety: We are about to drop the other copy of this pin, so
@@ -141,40 +148,55 @@ impl<'d, T: Pin> Flex<'d, T> {
        });
    }
+    /// Get whether the pin input level is high.
+    #[inline]
+    pub fn is_high(&mut self) -> bool {
+        !self.ref_is_low()
+    }
+    /// Get whether the pin input level is low.
    #[inline]
-    pub fn is_high(&self) -> bool {
+    pub fn is_low(&mut self) -> bool {
-        !self.is_low()
+        self.ref_is_low()
    }
    #[inline]
-    pub fn is_low(&self) -> bool {
+    pub(crate) fn ref_is_low(&self) -> bool {
        let state = self.pin.block().idr().read().idr(self.pin.pin() as _);
        state == vals::Idr::LOW
    }
+    /// Get the current pin input level.
    #[inline]
-    pub fn get_level(&self) -> Level {
+    pub fn get_level(&mut self) -> Level {
        self.is_high().into()
    }
+    /// Get whether the output level is set to high.
    #[inline]
-    pub fn is_set_high(&self) -> bool {
+    pub fn is_set_high(&mut self) -> bool {
-        !self.is_set_low()
+        !self.ref_is_set_low()
    }
-    /// Is the output pin set as low?
+    /// Get whether the output level is set to low.
    #[inline]
-    pub fn is_set_low(&self) -> bool {
+    pub fn is_set_low(&mut self) -> bool {
+        self.ref_is_set_low()
+    }
+    #[inline]
+    pub(crate) fn ref_is_set_low(&self) -> bool {
        let state = self.pin.block().odr().read().odr(self.pin.pin() as _);
        state == vals::Odr::LOW
    }
-    /// What level output is set to
+    /// Get the current output level.
    #[inline]
-    pub fn get_output_level(&self) -> Level {
+    pub fn get_output_level(&mut self) -> Level {
        self.is_set_high().into()
    }
+    /// Set the output as high.
    #[inline]
    pub fn set_high(&mut self) {
        self.pin.set_high();
@@ -186,6 +208,7 @@ impl<'d, T: Pin> Flex<'d, T> {
        self.pin.set_low();
    }
+    /// Set the output level.
    #[inline]
    pub fn set_level(&mut self, level: Level) {
        match level {
@@ -194,7 +217,7 @@ impl<'d, T: Pin> Flex<'d, T> {
        }
    }
-    /// Toggle pin output
+    /// Toggle the output level.
    #[inline]
    pub fn toggle(&mut self) {
        if self.is_set_low() {
@@ -232,8 +255,11 @@ impl<'d, T: Pin> Drop for Flex<'d, T> {
 #[derive(Debug, Eq, PartialEq, Copy, Clone)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Pull {
+    /// No pull
    None,
+    /// Pull up
    Up,
+    /// Pull down
    Down,
 }
@@ -251,6 +277,9 @@ impl From<Pull> for vals::Pupdr {
 }
 /// Speed settings
+///
+/// These vary dpeending on the chip, ceck the reference manual or datasheet for details.
+#[allow(missing_docs)]
 #[derive(Debug, Copy, Clone)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Speed {
@@ -295,6 +324,7 @@ pub struct Input<'d, T: Pin> {
 }
 impl<'d, T: Pin> Input<'d, T> {
+    /// Create GPIO input driver for a [Pin] with the provided [Pull] configuration.
    #[inline]
    pub fn new(pin: impl Peripheral<P = T> + 'd, pull: Pull) -> Self {
        let mut pin = Flex::new(pin);
@@ -302,6 +332,11 @@ impl<'d, T: Pin> Input<'d, T> {
        Self { pin }
    }
+    /// Type-erase (degrade) this pin into an `AnyPin`.
+    ///
+    /// This converts pin singletons (`PA5`, `PB6`, ...), which
+    /// are all different types, into the same type. It is useful for
+    /// creating arrays of pins, or avoiding generics.
    #[inline]
    pub fn degrade(self) -> Input<'d, AnyPin> {
        Input {
@@ -309,18 +344,21 @@ impl<'d, T: Pin> Input<'d, T> {
        }
    }
+    /// Get whether the pin input level is high.
    #[inline]
-    pub fn is_high(&self) -> bool {
+    pub fn is_high(&mut self) -> bool {
        self.pin.is_high()
    }
+    /// Get whether the pin input level is low.
    #[inline]
-    pub fn is_low(&self) -> bool {
+    pub fn is_low(&mut self) -> bool {
        self.pin.is_low()
    }
+    /// Get the current pin input level.
    #[inline]
-    pub fn get_level(&self) -> Level {
+    pub fn get_level(&mut self) -> Level {
        self.pin.get_level()
    }
 }
@@ -329,7 +367,9 @@ impl<'d, T: Pin> Input<'d, T> {
 #[derive(Debug, Eq, PartialEq, Copy, Clone)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Level {
+    /// Low
    Low,
+    /// High
    High,
 }
@@ -361,6 +401,7 @@ pub struct Output<'d, T: Pin> {
 }
 impl<'d, T: Pin> Output<'d, T> {
+    /// Create GPIO output driver for a [Pin] with the provided [Level] and [Speed] configuration.
    #[inline]
    pub fn new(pin: impl Peripheral<P = T> + 'd, initial_output: Level, speed: Speed) -> Self {
        let mut pin = Flex::new(pin);
@@ -372,6 +413,11 @@ impl<'d, T: Pin> Output<'d, T> {
        Self { pin }
    }
+    /// Type-erase (degrade) this pin into an `AnyPin`.
+    ///
+    /// This converts pin singletons (`PA5`, `PB6`, ...), which
+    /// are all different types, into the same type. It is useful for
+    /// creating arrays of pins, or avoiding generics.
    #[inline]
    pub fn degrade(self) -> Output<'d, AnyPin> {
        Output {
@@ -399,19 +445,19 @@ impl<'d, T: Pin> Output<'d, T> {
    /// Is the output pin set as high?
    #[inline]
-    pub fn is_set_high(&self) -> bool {
+    pub fn is_set_high(&mut self) -> bool {
        self.pin.is_set_high()
    }
    /// Is the output pin set as low?
    #[inline]
-    pub fn is_set_low(&self) -> bool {
+    pub fn is_set_low(&mut self) -> bool {
        self.pin.is_set_low()
    }
    /// What level output is set to
    #[inline]
-    pub fn get_output_level(&self) -> Level {
+    pub fn get_output_level(&mut self) -> Level {
        self.pin.get_output_level()
    }
@@ -432,6 +478,7 @@ pub struct OutputOpenDrain<'d, T: Pin> {
 }
 impl<'d, T: Pin> OutputOpenDrain<'d, T> {
+    /// Create a new GPIO open drain output driver for a [Pin] with the provided [Level] and [Speed], [Pull] configuration.
    #[inline]
    pub fn new(pin: impl Peripheral<P = T> + 'd, initial_output: Level, speed: Speed, pull: Pull) -> Self {
        let mut pin = Flex::new(pin);
@@ -445,6 +492,11 @@ impl<'d, T: Pin> OutputOpenDrain<'d, T> {
        Self { pin }
    }
+    /// Type-erase (degrade) this pin into an `AnyPin`.
+    ///
+    /// This converts pin singletons (`PA5`, `PB6`, ...), which
+    /// are all different types, into the same type. It is useful for
+    /// creating arrays of pins, or avoiding generics.
    #[inline]
    pub fn degrade(self) -> Output<'d, AnyPin> {
        Output {
@@ -452,19 +504,21 @@ impl<'d, T: Pin> OutputOpenDrain<'d, T> {
        }
    }
+    /// Get whether the pin input level is high.
    #[inline]
-    pub fn is_high(&self) -> bool {
+    pub fn is_high(&mut self) -> bool {
        !self.pin.is_low()
    }
+    /// Get whether the pin input level is low.
    #[inline]
-    pub fn is_low(&self) -> bool {
+    pub fn is_low(&mut self) -> bool {
        self.pin.is_low()
    }
-    /// Returns current pin level
+    /// Get the current pin input level.
    #[inline]
-    pub fn get_level(&self) -> Level {
+    pub fn get_level(&mut self) -> Level {
        self.pin.get_level()
    }
@@ -486,21 +540,21 @@ impl<'d, T: Pin> OutputOpenDrain<'d, T> {
        self.pin.set_level(level);
    }
-    /// Is the output pin set as high?
+    /// Get whether the output level is set to high.
    #[inline]
-    pub fn is_set_high(&self) -> bool {
+    pub fn is_set_high(&mut self) -> bool {
        self.pin.is_set_high()
    }
-    /// Is the output pin set as low?
+    /// Get whether the output level is set to low.
    #[inline]
-    pub fn is_set_low(&self) -> bool {
+    pub fn is_set_low(&mut self) -> bool {
        self.pin.is_set_low()
    }
-    /// What level output is set to
+    /// Get the current output level.
    #[inline]
-    pub fn get_output_level(&self) -> Level {
+    pub fn get_output_level(&mut self) -> Level {
        self.pin.get_output_level()
    }
@@ -511,8 +565,11 @@ impl<'d, T: Pin> OutputOpenDrain<'d, T> {
    }
 }
+/// GPIO output type
 pub enum OutputType {
+    /// Drive the pin both high or low.
    PushPull,
+    /// Drive the pin low, or don't drive it at all if the output level is high.
    OpenDrain,
 }
@@ -525,6 +582,7 @@ impl From<OutputType> for sealed::AFType {
    }
 }
+#[allow(missing_docs)]
 pub(crate) mod sealed {
    use super::*;
@@ -532,8 +590,11 @@ pub(crate) mod sealed {
    #[derive(Debug, Copy, Clone)]
    #[cfg_attr(feature = "defmt", derive(defmt::Format))]
    pub enum AFType {
+        /// Input
        Input,
+        /// Output, drive the pin both high or low.
        OutputPushPull,
+        /// Output, drive the pin low, or don't drive it at all if the output level is high.
        OutputOpenDrain,
    }
@@ -676,7 +737,11 @@ pub(crate) mod sealed {
    }
 }
+/// GPIO pin trait.
 pub trait Pin: Peripheral<P = Self> + Into<AnyPin> + sealed::Pin + Sized + 'static {
+    /// EXTI channel assigned to this pin.
+    ///
+    /// For example, PC4 uses EXTI4.
    #[cfg(feature = "exti")]
    type ExtiChannel: crate::exti::Channel;
@@ -692,7 +757,11 @@ pub trait Pin: Peripheral<P = Self> + Into<AnyPin> + sealed::Pin + Sized + 'stat
        self._port()
    }
-    /// Convert from concrete pin type PX_XX to type erased `AnyPin`.
+    /// Type-erase (degrade) this pin into an `AnyPin`.
+    ///
+    /// This converts pin singletons (`PA5`, `PB6`, ...), which
+    /// are all different types, into the same type. It is useful for
+    /// creating arrays of pins, or avoiding generics.
    #[inline]
    fn degrade(self) -> AnyPin {
        AnyPin {
@@ -701,12 +770,15 @@ pub trait Pin: Peripheral<P = Self> + Into<AnyPin> + sealed::Pin + Sized + 'stat
    }
 }
-// Type-erased GPIO pin
+/// Type-erased GPIO pin
 pub struct AnyPin {
    pin_port: u8,
 }
 impl AnyPin {
+    /// Unsafely create an `AnyPin` from a pin+port number.
+    ///
+    /// `pin_port` is `port_num * 16 + pin_num`, where `port_num` is 0 for port `A`, 1 for port `B`, etc...
    #[inline]
    pub unsafe fn steal(pin_port: u8) -> Self {
        Self { pin_port }
@@ -717,6 +789,8 @@ impl AnyPin {
        self.pin_port / 16
    }
+    /// Get the GPIO register block for this pin.
+    #[cfg(feature = "unstable-pac")]
    #[inline]
    pub fn block(&self) -> gpio::Gpio {
        pac::GPIO(self._port() as _)
@@ -777,12 +851,12 @@ impl<'d, T: Pin> embedded_hal_02::digital::v2::InputPin for Input<'d, T> {
    #[inline]
    fn is_high(&self) -> Result<bool, Self::Error> {
-        Ok(self.is_high())
+        Ok(!self.pin.ref_is_low())
    }
    #[inline]
    fn is_low(&self) -> Result<bool, Self::Error> {
-        Ok(self.is_low())
+        Ok(self.pin.ref_is_low())
    }
 }
@@ -805,13 +879,13 @@ impl<'d, T: Pin> embedded_hal_02::digital::v2::OutputPin for Output<'d, T> {
 impl<'d, T: Pin> embedded_hal_02::digital::v2::StatefulOutputPin for Output<'d, T> {
    #[inline]
    fn is_set_high(&self) -> Result<bool, Self::Error> {
-        Ok(self.is_set_high())
+        Ok(!self.pin.ref_is_set_low())
    }
    /// Is the output pin set as low?
    #[inline]
    fn is_set_low(&self) -> Result<bool, Self::Error> {
-        Ok(self.is_set_low())
+        Ok(self.pin.ref_is_set_low())
    }
 }
@@ -843,13 +917,13 @@ impl<'d, T: Pin> embedded_hal_02::digital::v2::OutputPin for OutputOpenDrain<'d,
 impl<'d, T: Pin> embedded_hal_02::digital::v2::StatefulOutputPin for OutputOpenDrain<'d, T> {
    #[inline]
    fn is_set_high(&self) -> Result<bool, Self::Error> {
-        Ok(self.is_set_high())
+        Ok(!self.pin.ref_is_set_low())
    }
    /// Is the output pin set as low?
    #[inline]
    fn is_set_low(&self) -> Result<bool, Self::Error> {
-        Ok(self.is_set_low())
+        Ok(self.pin.ref_is_set_low())
    }
 }
@@ -867,12 +941,12 @@ impl<'d, T: Pin> embedded_hal_02::digital::v2::InputPin for Flex<'d, T> {
    #[inline]
    fn is_high(&self) -> Result<bool, Self::Error> {
-        Ok(self.is_high())
+        Ok(!self.ref_is_low())
    }
    #[inline]
    fn is_low(&self) -> Result<bool, Self::Error> {
-        Ok(self.is_low())
+        Ok(self.ref_is_low())
    }
 }
@@ -895,13 +969,13 @@ impl<'d, T: Pin> embedded_hal_02::digital::v2::OutputPin for Flex<'d, T> {
 impl<'d, T: Pin> embedded_hal_02::digital::v2::StatefulOutputPin for Flex<'d, T> {
    #[inline]
    fn is_set_high(&self) -> Result<bool, Self::Error> {
-        Ok(self.is_set_high())
+        Ok(!self.ref_is_set_low())
    }
    /// Is the output pin set as low?
    #[inline]
    fn is_set_low(&self) -> Result<bool, Self::Error> {
-        Ok(self.is_set_low())
+        Ok(self.ref_is_set_low())
    }
 }
@@ -920,12 +994,12 @@ impl<'d, T: Pin> embedded_hal_1::digital::ErrorType for Input<'d, T> {
 impl<'d, T: Pin> embedded_hal_1::digital::InputPin for Input<'d, T> {
    #[inline]
-    fn is_high(&self) -> Result<bool, Self::Error> {
+    fn is_high(&mut self) -> Result<bool, Self::Error> {
        Ok(self.is_high())
    }
    #[inline]
-    fn is_low(&self) -> Result<bool, Self::Error> {
+    fn is_low(&mut self) -> Result<bool, Self::Error> {
        Ok(self.is_low())
    }
 }
@@ -948,13 +1022,13 @@ impl<'d, T: Pin> embedded_hal_1::digital::OutputPin for Output<'d, T> {
 impl<'d, T: Pin> embedded_hal_1::digital::StatefulOutputPin for Output<'d, T> {
    #[inline]
-    fn is_set_high(&self) -> Result<bool, Self::Error> {
+    fn is_set_high(&mut self) -> Result<bool, Self::Error> {
        Ok(self.is_set_high())
    }
    /// Is the output pin set as low?
    #[inline]
-    fn is_set_low(&self) -> Result<bool, Self::Error> {
+    fn is_set_low(&mut self) -> Result<bool, Self::Error> {
        Ok(self.is_set_low())
    }
 }
@@ -972,12 +1046,12 @@ impl<'d, T: Pin> embedded_hal_1::digital::ErrorType for OutputOpenDrain<'d, T> {
 impl<'d, T: Pin> embedded_hal_1::digital::InputPin for OutputOpenDrain<'d, T> {
    #[inline]
-    fn is_high(&self) -> Result<bool, Self::Error> {
+    fn is_high(&mut self) -> Result<bool, Self::Error> {
        Ok(self.is_high())
    }
    #[inline]
-    fn is_low(&self) -> Result<bool, Self::Error> {
+    fn is_low(&mut self) -> Result<bool, Self::Error> {
        Ok(self.is_low())
    }
 }
@@ -996,13 +1070,13 @@ impl<'d, T: Pin> embedded_hal_1::digital::OutputPin for OutputOpenDrain<'d, T> {
 impl<'d, T: Pin> embedded_hal_1::digital::StatefulOutputPin for OutputOpenDrain<'d, T> {
    #[inline]
-    fn is_set_high(&self) -> Result<bool, Self::Error> {
+    fn is_set_high(&mut self) -> Result<bool, Self::Error> {
        Ok(self.is_set_high())
    }
    /// Is the output pin set as low?
    #[inline]
-    fn is_set_low(&self) -> Result<bool, Self::Error> {
+    fn is_set_low(&mut self) -> Result<bool, Self::Error> {
        Ok(self.is_set_low())
    }
 }
@@ -1016,12 +1090,12 @@ impl<'d, T: Pin> embedded_hal_1::digital::ToggleableOutputPin for OutputOpenDrai
 impl<'d, T: Pin> embedded_hal_1::digital::InputPin for Flex<'d, T> {
    #[inline]
-    fn is_high(&self) -> Result<bool, Self::Error> {
+    fn is_high(&mut self) -> Result<bool, Self::Error> {
        Ok(self.is_high())
    }
    #[inline]
-    fn is_low(&self) -> Result<bool, Self::Error> {
+    fn is_low(&mut self) -> Result<bool, Self::Error> {
        Ok(self.is_low())
    }
 }
@@ -1051,17 +1125,18 @@ impl<'d, T: Pin> embedded_hal_1::digital::ErrorType for Flex<'d, T> {
 impl<'d, T: Pin> embedded_hal_1::digital::StatefulOutputPin for Flex<'d, T> {
    #[inline]
-    fn is_set_high(&self) -> Result<bool, Self::Error> {
+    fn is_set_high(&mut self) -> Result<bool, Self::Error> {
        Ok(self.is_set_high())
    }
    /// Is the output pin set as low?
    #[inline]
-    fn is_set_low(&self) -> Result<bool, Self::Error> {
+    fn is_set_low(&mut self) -> Result<bool, Self::Error> {
        Ok(self.is_set_low())
    }
 }
+/// Low-level GPIO manipulation.
 #[cfg(feature = "unstable-pac")]
 pub mod low_level {
    pub use super::sealed::*;
diff --git a/embassy-stm32/src/hrtim/mod.rs b/embassy-stm32/src/hrtim/mod.rs
index 17096d48c..faefaabbc 100644
--- a/embassy-stm32/src/hrtim/mod.rs
+++ b/embassy-stm32/src/hrtim/mod.rs
@@ -1,3 +1,5 @@
+//! High Resolution Timer (HRTIM)
 mod traits;
 use core::marker::PhantomData;
@@ -13,38 +15,42 @@ use crate::rcc::get_freqs;
 use crate::time::Hertz;
 use crate::Peripheral;
-pub enum Source {
+/// HRTIM burst controller instance.
-    Master,
-    ChA,
-    ChB,
-    ChC,
-    ChD,
-    ChE,
-    #[cfg(hrtim_v2)]
-    ChF,
-}
 pub struct BurstController<T: Instance> {
    phantom: PhantomData<T>,
 }
+/// HRTIM master instance.
 pub struct Master<T: Instance> {
    phantom: PhantomData<T>,
 }
+/// HRTIM channel A instance.
 pub struct ChA<T: Instance> {
    phantom: PhantomData<T>,
 }
+/// HRTIM channel B instance.
 pub struct ChB<T: Instance> {
    phantom: PhantomData<T>,
 }
+/// HRTIM channel C instance.
 pub struct ChC<T: Instance> {
    phantom: PhantomData<T>,
 }
+/// HRTIM channel D instance.
 pub struct ChD<T: Instance> {
    phantom: PhantomData<T>,
 }
+/// HRTIM channel E instance.
 pub struct ChE<T: Instance> {
    phantom: PhantomData<T>,
 }
+/// HRTIM channel F instance.
 #[cfg(hrtim_v2)]
 pub struct ChF<T: Instance> {
    phantom: PhantomData<T>,
@@ -58,22 +64,26 @@ mod sealed {
    }
 }
+/// Advanced channel instance trait.
 pub trait AdvancedChannel<T: Instance>: sealed::AdvancedChannel<T> {}
-pub struct PwmPin<'d, Perip, Channel> {
+/// HRTIM PWM pin.
+pub struct PwmPin<'d, T, C> {
    _pin: PeripheralRef<'d, AnyPin>,
-    phantom: PhantomData<(Perip, Channel)>,
+    phantom: PhantomData<(T, C)>,
 }
-pub struct ComplementaryPwmPin<'d, Perip, Channel> {
+/// HRTIM complementary PWM pin.
+pub struct ComplementaryPwmPin<'d, T, C> {
    _pin: PeripheralRef<'d, AnyPin>,
-    phantom: PhantomData<(Perip, Channel)>,
+    phantom: PhantomData<(T, C)>,
 }
 macro_rules! advanced_channel_impl {
    ($new_chx:ident, $channel:tt, $ch_num:expr, $pin_trait:ident, $complementary_pin_trait:ident) => {
-        impl<'d, Perip: Instance> PwmPin<'d, Perip, $channel<Perip>> {
+        impl<'d, T: Instance> PwmPin<'d, T, $channel<T>> {
-            pub fn $new_chx(pin: impl Peripheral<P = impl $pin_trait<Perip>> + 'd) -> Self {
+            #[doc = concat!("Create a new ", stringify!($channel), " PWM pin instance.")]
+            pub fn $new_chx(pin: impl Peripheral<P = impl $pin_trait<T>> + 'd) -> Self {
                into_ref!(pin);
                critical_section::with(|_| {
                    pin.set_low();
@@ -88,8 +98,9 @@ macro_rules! advanced_channel_impl {
            }
        }
-        impl<'d, Perip: Instance> ComplementaryPwmPin<'d, Perip, $channel<Perip>> {
+        impl<'d, T: Instance> ComplementaryPwmPin<'d, T, $channel<T>> {
-            pub fn $new_chx(pin: impl Peripheral<P = impl $complementary_pin_trait<Perip>> + 'd) -> Self {
+            #[doc = concat!("Create a new ", stringify!($channel), " complementary PWM pin instance.")]
+            pub fn $new_chx(pin: impl Peripheral<P = impl $complementary_pin_trait<T>> + 'd) -> Self {
                into_ref!(pin);
                critical_section::with(|_| {
                    pin.set_low();
@@ -124,18 +135,29 @@ advanced_channel_impl!(new_chf, ChF, 5, ChannelFPin, ChannelFComplementaryPin);
 /// Struct used to divide a high resolution timer into multiple channels
 pub struct AdvancedPwm<'d, T: Instance> {
    _inner: PeripheralRef<'d, T>,
+    /// Master instance.
    pub master: Master<T>,
+    /// Burst controller.
    pub burst_controller: BurstController<T>,
+    /// Channel A.
    pub ch_a: ChA<T>,
+    /// Channel B.
    pub ch_b: ChB<T>,
+    /// Channel C.
    pub ch_c: ChC<T>,
+    /// Channel D.
    pub ch_d: ChD<T>,
+    /// Channel E.
    pub ch_e: ChE<T>,
+    /// Channel F.
    #[cfg(hrtim_v2)]
    pub ch_f: ChF<T>,
 }
 impl<'d, T: Instance> AdvancedPwm<'d, T> {
+    /// Create a new HRTIM driver.
+    ///
+    /// This splits the HRTIM into its constituent parts, which you can then use individually.
    pub fn new(
        tim: impl Peripheral<P = T> + 'd,
        _cha: Option<PwmPin<'d, T, ChA<T>>>,
@@ -198,13 +220,7 @@ impl<'d, T: Instance> AdvancedPwm<'d, T> {
    }
 }
-impl<T: Instance> BurstController<T> {
+/// Fixed-frequency bridge converter driver.
-    pub fn set_source(&mut self, _source: Source) {
-        todo!("burst mode control registers not implemented")
-    }
-}
-/// Represents a fixed-frequency bridge converter
 ///
 /// Our implementation of the bridge converter uses a single channel and three compare registers,
 /// allowing implementation of a synchronous buck or boost converter in continuous or discontinuous
@@ -223,6 +239,7 @@ pub struct BridgeConverter<T: Instance, C: AdvancedChannel<T>> {
 }
 impl<T: Instance, C: AdvancedChannel<T>> BridgeConverter<T, C> {
+    /// Create a new HRTIM bridge converter driver.
    pub fn new(_channel: C, frequency: Hertz) -> Self {
        use crate::pac::hrtim::vals::{Activeeffect, Inactiveeffect};
@@ -279,14 +296,17 @@ impl<T: Instance, C: AdvancedChannel<T>> BridgeConverter<T, C> {
        }
    }
+    /// Start HRTIM.
    pub fn start(&mut self) {
        T::regs().mcr().modify(|w| w.set_tcen(C::raw(), true));
    }
+    /// Stop HRTIM.
    pub fn stop(&mut self) {
        T::regs().mcr().modify(|w| w.set_tcen(C::raw(), false));
    }
+    /// Enable burst mode.
    pub fn enable_burst_mode(&mut self) {
        T::regs().tim(C::raw()).outr().modify(|w| {
            // Enable Burst Mode
@@ -299,6 +319,7 @@ impl<T: Instance, C: AdvancedChannel<T>> BridgeConverter<T, C> {
        })
    }
+    /// Disable burst mode.
    pub fn disable_burst_mode(&mut self) {
        T::regs().tim(C::raw()).outr().modify(|w| {
            // Disable Burst Mode
@@ -355,7 +376,7 @@ impl<T: Instance, C: AdvancedChannel<T>> BridgeConverter<T, C> {
    }
 }
-/// Represents a variable-frequency resonant converter
+/// Variable-frequency resonant converter driver.
 ///
 /// This implementation of a resonsant converter is appropriate for a half or full bridge,
 /// but does not include secondary rectification, which is appropriate for applications
@@ -368,6 +389,7 @@ pub struct ResonantConverter<T: Instance, C: AdvancedChannel<T>> {
 }
 impl<T: Instance, C: AdvancedChannel<T>> ResonantConverter<T, C> {
+    /// Create a new variable-frequency resonant converter driver.
    pub fn new(_channel: C, min_frequency: Hertz, max_frequency: Hertz) -> Self {
        T::set_channel_frequency(C::raw(), min_frequency);
@@ -406,6 +428,7 @@ impl<T: Instance, C: AdvancedChannel<T>> ResonantConverter<T, C> {
        T::set_channel_dead_time(C::raw(), value);
    }
+    /// Set the timer period.
    pub fn set_period(&mut self, period: u16) {
        assert!(period < self.max_period);
        assert!(period > self.min_period);
diff --git a/embassy-stm32/src/hrtim/traits.rs b/embassy-stm32/src/hrtim/traits.rs
index 34a363a1f..cfd31c47c 100644
--- a/embassy-stm32/src/hrtim/traits.rs
+++ b/embassy-stm32/src/hrtim/traits.rs
@@ -125,7 +125,6 @@ pub(crate) mod sealed {
        }
        /// Set the dead time as a proportion of max_duty
        fn set_channel_dead_time(channel: usize, dead_time: u16) {
            let regs = Self::regs();
@@ -148,13 +147,10 @@ pub(crate) mod sealed {
                w.set_dtr(dt_val as u16);
            });
        }
-        //        fn enable_outputs(enable: bool);
-        //
-        //        fn enable_channel(&mut self, channel: usize, enable: bool);
    }
 }
+/// HRTIM instance trait.
 pub trait Instance: sealed::Instance + 'static {}
 foreach_interrupt! {
diff --git a/embassy-stm32/src/i2c/mod.rs b/embassy-stm32/src/i2c/mod.rs
index d2a50cf7e..2416005b5 100644
--- a/embassy-stm32/src/i2c/mod.rs
+++ b/embassy-stm32/src/i2c/mod.rs
@@ -1,30 +1,180 @@
+//! Inter-Integrated-Circuit (I2C)
 #![macro_use]
-use core::marker::PhantomData;
-use crate::dma::NoDma;
-use crate::interrupt;
 #[cfg_attr(i2c_v1, path = "v1.rs")]
 #[cfg_attr(i2c_v2, path = "v2.rs")]
 mod _version;
-pub use _version::*;
+use core::future::Future;
+use core::marker::PhantomData;
+use embassy_hal_internal::{into_ref, Peripheral, PeripheralRef};
 use embassy_sync::waitqueue::AtomicWaker;
+#[cfg(feature = "time")]
+use embassy_time::{Duration, Instant};
-use crate::peripherals;
+use crate::dma::NoDma;
+use crate::gpio::sealed::AFType;
+use crate::gpio::Pull;
+use crate::interrupt::typelevel::Interrupt;
+use crate::time::Hertz;
+use crate::{interrupt, peripherals};
+/// I2C error.
 #[derive(Debug, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Error {
+    /// Bus error
    Bus,
+    /// Arbitration lost
    Arbitration,
+    /// ACK not received (either to the address or to a data byte)
    Nack,
+    /// Timeout
    Timeout,
+    /// CRC error
    Crc,
+    /// Overrun error
    Overrun,
+    /// Zero-length transfers are not allowed.
    ZeroLengthTransfer,
 }
+/// I2C config
+#[non_exhaustive]
+#[derive(Copy, Clone)]
+pub struct Config {
+    /// Enable internal pullup on SDA.
+    ///
+    /// Using external pullup resistors is recommended for I2C. If you do
+    /// have external pullups you should not enable this.
+    pub sda_pullup: bool,
+    /// Enable internal pullup on SCL.
+    ///
+    /// Using external pullup resistors is recommended for I2C. If you do
+    /// have external pullups you should not enable this.
+    pub scl_pullup: bool,
+    /// Timeout.
+    #[cfg(feature = "time")]
+    pub timeout: embassy_time::Duration,
+}
+impl Default for Config {
+    fn default() -> Self {
+        Self {
+            sda_pullup: false,
+            scl_pullup: false,
+            #[cfg(feature = "time")]
+            timeout: embassy_time::Duration::from_millis(1000),
+        }
+    }
+}
+/// I2C driver.
+pub struct I2c<'d, T: Instance, TXDMA = NoDma, RXDMA = NoDma> {
+    _peri: PeripheralRef<'d, T>,
+    #[allow(dead_code)]
+    tx_dma: PeripheralRef<'d, TXDMA>,
+    #[allow(dead_code)]
+    rx_dma: PeripheralRef<'d, RXDMA>,
+    #[cfg(feature = "time")]
+    timeout: Duration,
+}
+impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
+    /// Create a new I2C driver.
+    pub fn new(
+        peri: impl Peripheral<P = T> + 'd,
+        scl: impl Peripheral<P = impl SclPin<T>> + 'd,
+        sda: impl Peripheral<P = impl SdaPin<T>> + 'd,
+        _irq: impl interrupt::typelevel::Binding<T::EventInterrupt, EventInterruptHandler<T>>
+            + interrupt::typelevel::Binding<T::ErrorInterrupt, ErrorInterruptHandler<T>>
+            + 'd,
+        tx_dma: impl Peripheral<P = TXDMA> + 'd,
+        rx_dma: impl Peripheral<P = RXDMA> + 'd,
+        freq: Hertz,
+        config: Config,
+    ) -> Self {
+        into_ref!(peri, scl, sda, tx_dma, rx_dma);
+        T::enable_and_reset();
+        scl.set_as_af_pull(
+            scl.af_num(),
+            AFType::OutputOpenDrain,
+            match config.scl_pullup {
+                true => Pull::Up,
+                false => Pull::None,
+            },
+        );
+        sda.set_as_af_pull(
+            sda.af_num(),
+            AFType::OutputOpenDrain,
+            match config.sda_pullup {
+                true => Pull::Up,
+                false => Pull::None,
+            },
+        );
+        unsafe { T::EventInterrupt::enable() };
+        unsafe { T::ErrorInterrupt::enable() };
+        let mut this = Self {
+            _peri: peri,
+            tx_dma,
+            rx_dma,
+            #[cfg(feature = "time")]
+            timeout: config.timeout,
+        };
+        this.init(freq, config);
+        this
+    }
+    fn timeout(&self) -> Timeout {
+        Timeout {
+            #[cfg(feature = "time")]
+            deadline: Instant::now() + self.timeout,
+        }
+    }
+}
+#[derive(Copy, Clone)]
+struct Timeout {
+    #[cfg(feature = "time")]
+    deadline: Instant,
+}
+#[allow(dead_code)]
+impl Timeout {
+    #[inline]
+    fn check(self) -> Result<(), Error> {
+        #[cfg(feature = "time")]
+        if Instant::now() > self.deadline {
+            return Err(Error::Timeout);
+        }
+        Ok(())
+    }
+    #[inline]
+    fn with<R>(self, fut: impl Future<Output = Result<R, Error>>) -> impl Future<Output = Result<R, Error>> {
+        #[cfg(feature = "time")]
+        {
+            use futures::FutureExt;
+            embassy_futures::select::select(embassy_time::Timer::at(self.deadline), fut).map(|r| match r {
+                embassy_futures::select::Either::First(_) => Err(Error::Timeout),
+                embassy_futures::select::Either::Second(r) => r,
+            })
+        }
+        #[cfg(not(feature = "time"))]
+        fut
+    }
+}
 pub(crate) mod sealed {
    use super::*;
@@ -47,8 +197,11 @@ pub(crate) mod sealed {
    }
 }
+/// I2C peripheral instance
 pub trait Instance: sealed::Instance + 'static {
+    /// Event interrupt for this instance
    type EventInterrupt: interrupt::typelevel::Interrupt;
+    /// Error interrupt for this instance
    type ErrorInterrupt: interrupt::typelevel::Interrupt;
 }
@@ -57,7 +210,7 @@ pin_trait!(SdaPin, Instance);
 dma_trait!(RxDma, Instance);
 dma_trait!(TxDma, Instance);
-/// Interrupt handler.
+/// Event interrupt handler.
 pub struct EventInterruptHandler<T: Instance> {
    _phantom: PhantomData<T>,
 }
@@ -68,6 +221,7 @@ impl<T: Instance> interrupt::typelevel::Handler<T::EventInterrupt> for EventInte
    }
 }
+/// Error interrupt handler.
 pub struct ErrorInterruptHandler<T: Instance> {
    _phantom: PhantomData<T>,
 }
diff --git a/embassy-stm32/src/i2c/v1.rs b/embassy-stm32/src/i2c/v1.rs
index b62ee8246..cbbc201de 100644
--- a/embassy-stm32/src/i2c/v1.rs
+++ b/embassy-stm32/src/i2c/v1.rs
@@ -1,21 +1,32 @@
+//! # I2Cv1
+//!
+//! This implementation is used for STM32F1, STM32F2, STM32F4, and STM32L1 devices.
+//!
+//! All other devices (as of 2023-12-28) use [`v2`](super::v2) instead.
 use core::future::poll_fn;
-use core::marker::PhantomData;
 use core::task::Poll;
 use embassy_embedded_hal::SetConfig;
 use embassy_futures::select::{select, Either};
 use embassy_hal_internal::drop::OnDrop;
-use embassy_hal_internal::{into_ref, PeripheralRef};
 use super::*;
-use crate::dma::{NoDma, Transfer};
+use crate::dma::Transfer;
-use crate::gpio::sealed::AFType;
-use crate::gpio::Pull;
-use crate::interrupt::typelevel::Interrupt;
 use crate::pac::i2c;
 use crate::time::Hertz;
-use crate::{interrupt, Peripheral};
+// /!\                      /!\
+// /!\ Implementation note! /!\
+// /!\                      /!\
+//
+// It's somewhat unclear whether using interrupts here in a *strictly* one-shot style is actually
+// what we want! If you are looking in this file because you are doing async I2C and your code is
+// just totally hanging (sometimes), maybe swing by this issue:
+// <https://github.com/embassy-rs/embassy/issues/2372>.
+//
+// There's some more details there, and we might have a fix for you. But please let us know if you
+// hit a case like this!
 pub unsafe fn on_interrupt<T: Instance>() {
    let regs = T::regs();
    // i2c v2 only woke the task on transfer complete interrupts. v1 uses interrupts for a bunch of
@@ -30,55 +41,8 @@ pub unsafe fn on_interrupt<T: Instance>() {
    });
 }
-#[non_exhaustive]
-#[derive(Copy, Clone, Default)]
-pub struct Config {
-    pub sda_pullup: bool,
-    pub scl_pullup: bool,
-}
-pub struct I2c<'d, T: Instance, TXDMA = NoDma, RXDMA = NoDma> {
-    phantom: PhantomData<&'d mut T>,
-    #[allow(dead_code)]
-    tx_dma: PeripheralRef<'d, TXDMA>,
-    #[allow(dead_code)]
-    rx_dma: PeripheralRef<'d, RXDMA>,
-}
 impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
-    pub fn new(
+    pub(crate) fn init(&mut self, freq: Hertz, _config: Config) {
-        _peri: impl Peripheral<P = T> + 'd,
-        scl: impl Peripheral<P = impl SclPin<T>> + 'd,
-        sda: impl Peripheral<P = impl SdaPin<T>> + 'd,
-        _irq: impl interrupt::typelevel::Binding<T::EventInterrupt, EventInterruptHandler<T>>
-            + interrupt::typelevel::Binding<T::ErrorInterrupt, ErrorInterruptHandler<T>>
-            + 'd,
-        tx_dma: impl Peripheral<P = TXDMA> + 'd,
-        rx_dma: impl Peripheral<P = RXDMA> + 'd,
-        freq: Hertz,
-        config: Config,
-    ) -> Self {
-        into_ref!(scl, sda, tx_dma, rx_dma);
-        T::enable_and_reset();
-        scl.set_as_af_pull(
-            scl.af_num(),
-            AFType::OutputOpenDrain,
-            match config.scl_pullup {
-                true => Pull::Up,
-                false => Pull::None,
-            },
-        );
-        sda.set_as_af_pull(
-            sda.af_num(),
-            AFType::OutputOpenDrain,
-            match config.sda_pullup {
-                true => Pull::Up,
-                false => Pull::None,
-            },
-        );
        T::regs().cr1().modify(|reg| {
            reg.set_pe(false);
            //reg.set_anfoff(false);
@@ -101,15 +65,6 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
        T::regs().cr1().modify(|reg| {
            reg.set_pe(true);
        });
-        unsafe { T::EventInterrupt::enable() };
-        unsafe { T::ErrorInterrupt::enable() };
-        Self {
-            phantom: PhantomData,
-            tx_dma,
-            rx_dma,
-        }
    }
    fn check_and_clear_error_flags() -> Result<i2c::regs::Sr1, Error> {
@@ -169,12 +124,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
        Ok(sr1)
    }
-    fn write_bytes(
+    fn write_bytes(&mut self, addr: u8, bytes: &[u8], timeout: Timeout) -> Result<(), Error> {
-        &mut self,
-        addr: u8,
-        bytes: &[u8],
-        check_timeout: impl Fn() -> Result<(), Error>,
-    ) -> Result<(), Error> {
        // Send a START condition
        T::regs().cr1().modify(|reg| {
@@ -183,7 +133,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
        // Wait until START condition was generated
        while !Self::check_and_clear_error_flags()?.start() {
-            check_timeout()?;
+            timeout.check()?;
        }
        // Also wait until signalled we're master and everything is waiting for us
@@ -193,7 +143,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
            let sr2 = T::regs().sr2().read();
            !sr2.msl() && !sr2.busy()
        } {
-            check_timeout()?;
+            timeout.check()?;
        }
        // Set up current address, we're trying to talk to
@@ -203,7 +153,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
        // Wait for the address to be acknowledged
        // Check for any I2C errors. If a NACK occurs, the ADDR bit will never be set.
        while !Self::check_and_clear_error_flags()?.addr() {
-            check_timeout()?;
+            timeout.check()?;
        }
        // Clear condition by reading SR2
@@ -211,20 +161,20 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
        // Send bytes
        for c in bytes {
-            self.send_byte(*c, &check_timeout)?;
+            self.send_byte(*c, timeout)?;
        }
        // Fallthrough is success
        Ok(())
    }
-    fn send_byte(&self, byte: u8, check_timeout: impl Fn() -> Result<(), Error>) -> Result<(), Error> {
+    fn send_byte(&self, byte: u8, timeout: Timeout) -> Result<(), Error> {
        // Wait until we're ready for sending
        while {
            // Check for any I2C errors. If a NACK occurs, the ADDR bit will never be set.
            !Self::check_and_clear_error_flags()?.txe()
        } {
-            check_timeout()?;
+            timeout.check()?;
        }
        // Push out a byte of data
@@ -235,32 +185,27 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
            // Check for any potential error conditions.
            !Self::check_and_clear_error_flags()?.btf()
        } {
-            check_timeout()?;
+            timeout.check()?;
        }
        Ok(())
    }
-    fn recv_byte(&self, check_timeout: impl Fn() -> Result<(), Error>) -> Result<u8, Error> {
+    fn recv_byte(&self, timeout: Timeout) -> Result<u8, Error> {
        while {
            // Check for any potential error conditions.
            Self::check_and_clear_error_flags()?;
            !T::regs().sr1().read().rxne()
        } {
-            check_timeout()?;
+            timeout.check()?;
        }
        let value = T::regs().dr().read().dr();
        Ok(value)
    }
-    pub fn blocking_read_timeout(
+    fn blocking_read_timeout(&mut self, addr: u8, buffer: &mut [u8], timeout: Timeout) -> Result<(), Error> {
-        &mut self,
-        addr: u8,
-        buffer: &mut [u8],
-        check_timeout: impl Fn() -> Result<(), Error>,
-    ) -> Result<(), Error> {
        if let Some((last, buffer)) = buffer.split_last_mut() {
            // Send a START condition and set ACK bit
            T::regs().cr1().modify(|reg| {
@@ -270,7 +215,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
            // Wait until START condition was generated
            while !Self::check_and_clear_error_flags()?.start() {
-                check_timeout()?;
+                timeout.check()?;
            }
            // Also wait until signalled we're master and everything is waiting for us
@@ -278,7 +223,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
                let sr2 = T::regs().sr2().read();
                !sr2.msl() && !sr2.busy()
            } {
-                check_timeout()?;
+                timeout.check()?;
            }
            // Set up current address, we're trying to talk to
@@ -287,7 +232,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
            // Wait until address was sent
            // Wait for the address to be acknowledged
            while !Self::check_and_clear_error_flags()?.addr() {
-                check_timeout()?;
+                timeout.check()?;
            }
            // Clear condition by reading SR2
@@ -295,7 +240,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
            // Receive bytes into buffer
            for c in buffer {
-                *c = self.recv_byte(&check_timeout)?;
+                *c = self.recv_byte(timeout)?;
            }
            // Prepare to send NACK then STOP after next byte
@@ -305,11 +250,11 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
            });
            // Receive last byte
-            *last = self.recv_byte(&check_timeout)?;
+            *last = self.recv_byte(timeout)?;
            // Wait for the STOP to be sent.
            while T::regs().cr1().read().stop() {
-                check_timeout()?;
+                timeout.check()?;
            }
            // Fallthrough is success
@@ -319,49 +264,37 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
        }
    }
+    /// Blocking read.
    pub fn blocking_read(&mut self, addr: u8, read: &mut [u8]) -> Result<(), Error> {
-        self.blocking_read_timeout(addr, read, || Ok(()))
+        self.blocking_read_timeout(addr, read, self.timeout())
    }
-    pub fn blocking_write_timeout(
+    /// Blocking write.
-        &mut self,
+    pub fn blocking_write(&mut self, addr: u8, write: &[u8]) -> Result<(), Error> {
-        addr: u8,
+        let timeout = self.timeout();
-        write: &[u8],
-        check_timeout: impl Fn() -> Result<(), Error>,
+        self.write_bytes(addr, write, timeout)?;
-    ) -> Result<(), Error> {
-        self.write_bytes(addr, write, &check_timeout)?;
        // Send a STOP condition
        T::regs().cr1().modify(|reg| reg.set_stop(true));
        // Wait for STOP condition to transmit.
        while T::regs().cr1().read().stop() {
-            check_timeout()?;
+            timeout.check()?;
        }
        // Fallthrough is success
        Ok(())
    }
-    pub fn blocking_write(&mut self, addr: u8, write: &[u8]) -> Result<(), Error> {
+    /// Blocking write, restart, read.
-        self.blocking_write_timeout(addr, write, || Ok(()))
+    pub fn blocking_write_read(&mut self, addr: u8, write: &[u8], read: &mut [u8]) -> Result<(), Error> {
-    }
+        let timeout = self.timeout();
-    pub fn blocking_write_read_timeout(
+        self.write_bytes(addr, write, timeout)?;
-        &mut self,
+        self.blocking_read_timeout(addr, read, timeout)?;
-        addr: u8,
-        write: &[u8],
-        read: &mut [u8],
-        check_timeout: impl Fn() -> Result<(), Error>,
-    ) -> Result<(), Error> {
-        self.write_bytes(addr, write, &check_timeout)?;
-        self.blocking_read_timeout(addr, read, &check_timeout)?;
        Ok(())
    }
-    pub fn blocking_write_read(&mut self, addr: u8, write: &[u8], read: &mut [u8]) -> Result<(), Error> {
-        self.blocking_write_read_timeout(addr, write, read, || Ok(()))
-    }
    // Async
    #[inline] // pretty sure this should always be inlined
@@ -459,6 +392,9 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
                        T::regs().sr2().read();
                        Poll::Ready(Ok(()))
                    } else {
+                        // If we need to go around, then re-enable the interrupts, otherwise nothing
+                        // can wake us up and we'll hang.
+                        Self::enable_interrupts();
                        Poll::Pending
                    }
                }
@@ -522,6 +458,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
        Ok(())
    }
+    /// Write.
    pub async fn write(&mut self, address: u8, write: &[u8]) -> Result<(), Error>
    where
        TXDMA: crate::i2c::TxDma<T>,
@@ -544,6 +481,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
        Ok(())
    }
+    /// Read.
    pub async fn read(&mut self, address: u8, buffer: &mut [u8]) -> Result<(), Error>
    where
        RXDMA: crate::i2c::RxDma<T>,
@@ -703,6 +641,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
        Ok(())
    }
+    /// Write, restart, read.
    pub async fn write_read(&mut self, address: u8, write: &[u8], read: &mut [u8]) -> Result<(), Error>
    where
        RXDMA: crate::i2c::RxDma<T>,
diff --git a/embassy-stm32/src/i2c/v2.rs b/embassy-stm32/src/i2c/v2.rs
index 8c20e1c54..bd3abaac1 100644
--- a/embassy-stm32/src/i2c/v2.rs
+++ b/embassy-stm32/src/i2c/v2.rs
@@ -4,37 +4,13 @@ use core::task::Poll;
 use embassy_embedded_hal::SetConfig;
 use embassy_hal_internal::drop::OnDrop;
-use embassy_hal_internal::{into_ref, PeripheralRef};
-#[cfg(feature = "time")]
-use embassy_time::{Duration, Instant};
 use super::*;
-use crate::dma::{NoDma, Transfer};
+use crate::dma::Transfer;
-use crate::gpio::sealed::AFType;
-use crate::gpio::Pull;
-use crate::interrupt::typelevel::Interrupt;
 use crate::pac::i2c;
 use crate::time::Hertz;
-use crate::{interrupt, Peripheral};
-#[cfg(feature = "time")]
-fn timeout_fn(timeout: Duration) -> impl Fn() -> Result<(), Error> {
-    let deadline = Instant::now() + timeout;
-    move || {
-        if Instant::now() > deadline {
-            Err(Error::Timeout)
-        } else {
-            Ok(())
-        }
-    }
-}
-#[cfg(not(feature = "time"))]
-pub fn no_timeout_fn() -> impl Fn() -> Result<(), Error> {
-    move || Ok(())
-}
-pub unsafe fn on_interrupt<T: Instance>() {
+pub(crate) unsafe fn on_interrupt<T: Instance>() {
    let regs = T::regs();
    let isr = regs.isr().read();
@@ -48,70 +24,8 @@ pub unsafe fn on_interrupt<T: Instance>() {
    });
 }
-#[non_exhaustive]
-#[derive(Copy, Clone)]
-pub struct Config {
-    pub sda_pullup: bool,
-    pub scl_pullup: bool,
-    #[cfg(feature = "time")]
-    pub transaction_timeout: Duration,
-}
-impl Default for Config {
-    fn default() -> Self {
-        Self {
-            sda_pullup: false,
-            scl_pullup: false,
-            #[cfg(feature = "time")]
-            transaction_timeout: Duration::from_millis(100),
-        }
-    }
-}
-pub struct I2c<'d, T: Instance, TXDMA = NoDma, RXDMA = NoDma> {
-    _peri: PeripheralRef<'d, T>,
-    #[allow(dead_code)]
-    tx_dma: PeripheralRef<'d, TXDMA>,
-    #[allow(dead_code)]
-    rx_dma: PeripheralRef<'d, RXDMA>,
-    #[cfg(feature = "time")]
-    timeout: Duration,
-}
 impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
-    pub fn new(
+    pub(crate) fn init(&mut self, freq: Hertz, _config: Config) {
-        peri: impl Peripheral<P = T> + 'd,
-        scl: impl Peripheral<P = impl SclPin<T>> + 'd,
-        sda: impl Peripheral<P = impl SdaPin<T>> + 'd,
-        _irq: impl interrupt::typelevel::Binding<T::EventInterrupt, EventInterruptHandler<T>>
-            + interrupt::typelevel::Binding<T::ErrorInterrupt, ErrorInterruptHandler<T>>
-            + 'd,
-        tx_dma: impl Peripheral<P = TXDMA> + 'd,
-        rx_dma: impl Peripheral<P = RXDMA> + 'd,
-        freq: Hertz,
-        config: Config,
-    ) -> Self {
-        into_ref!(peri, scl, sda, tx_dma, rx_dma);
-        T::enable_and_reset();
-        scl.set_as_af_pull(
-            scl.af_num(),
-            AFType::OutputOpenDrain,
-            match config.scl_pullup {
-                true => Pull::Up,
-                false => Pull::None,
-            },
-        );
-        sda.set_as_af_pull(
-            sda.af_num(),
-            AFType::OutputOpenDrain,
-            match config.sda_pullup {
-                true => Pull::Up,
-                false => Pull::None,
-            },
-        );
        T::regs().cr1().modify(|reg| {
            reg.set_pe(false);
            reg.set_anfoff(false);
@@ -130,17 +44,6 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
        T::regs().cr1().modify(|reg| {
            reg.set_pe(true);
        });
-        unsafe { T::EventInterrupt::enable() };
-        unsafe { T::ErrorInterrupt::enable() };
-        Self {
-            _peri: peri,
-            tx_dma,
-            rx_dma,
-            #[cfg(feature = "time")]
-            timeout: config.transaction_timeout,
-        }
    }
    fn master_stop(&mut self) {
@@ -153,7 +56,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
        stop: Stop,
        reload: bool,
        restart: bool,
-        check_timeout: impl Fn() -> Result<(), Error>,
+        timeout: Timeout,
    ) -> Result<(), Error> {
        assert!(length < 256);
@@ -162,7 +65,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
            // automatically. This could be up to 50% of a bus
            // cycle (ie. up to 0.5/freq)
            while T::regs().cr2().read().start() {
-                check_timeout()?;
+                timeout.check()?;
            }
        }
@@ -189,20 +92,14 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
        Ok(())
    }
-    fn master_write(
+    fn master_write(address: u8, length: usize, stop: Stop, reload: bool, timeout: Timeout) -> Result<(), Error> {
-        address: u8,
-        length: usize,
-        stop: Stop,
-        reload: bool,
-        check_timeout: impl Fn() -> Result<(), Error>,
-    ) -> Result<(), Error> {
        assert!(length < 256);
        // Wait for any previous address sequence to end
        // automatically. This could be up to 50% of a bus
        // cycle (ie. up to 0.5/freq)
        while T::regs().cr2().read().start() {
-            check_timeout()?;
+            timeout.check()?;
        }
        let reload = if reload {
@@ -227,15 +124,11 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
        Ok(())
    }
-    fn master_continue(
+    fn master_continue(length: usize, reload: bool, timeout: Timeout) -> Result<(), Error> {
-        length: usize,
-        reload: bool,
-        check_timeout: impl Fn() -> Result<(), Error>,
-    ) -> Result<(), Error> {
        assert!(length < 256 && length > 0);
        while !T::regs().isr().read().tcr() {
-            check_timeout()?;
+            timeout.check()?;
        }
        let reload = if reload {
@@ -261,7 +154,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
        }
    }
-    fn wait_txe(&self, check_timeout: impl Fn() -> Result<(), Error>) -> Result<(), Error> {
+    fn wait_txe(&self, timeout: Timeout) -> Result<(), Error> {
        loop {
            let isr = T::regs().isr().read();
            if isr.txe() {
@@ -278,11 +171,11 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
                return Err(Error::Nack);
            }
-            check_timeout()?;
+            timeout.check()?;
        }
    }
-    fn wait_rxne(&self, check_timeout: impl Fn() -> Result<(), Error>) -> Result<(), Error> {
+    fn wait_rxne(&self, timeout: Timeout) -> Result<(), Error> {
        loop {
            let isr = T::regs().isr().read();
            if isr.rxne() {
@@ -299,11 +192,11 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
                return Err(Error::Nack);
            }
-            check_timeout()?;
+            timeout.check()?;
        }
    }
-    fn wait_tc(&self, check_timeout: impl Fn() -> Result<(), Error>) -> Result<(), Error> {
+    fn wait_tc(&self, timeout: Timeout) -> Result<(), Error> {
        loop {
            let isr = T::regs().isr().read();
            if isr.tc() {
@@ -320,17 +213,11 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
                return Err(Error::Nack);
            }
-            check_timeout()?;
+            timeout.check()?;
        }
    }
-    fn read_internal(
+    fn read_internal(&mut self, address: u8, read: &mut [u8], restart: bool, timeout: Timeout) -> Result<(), Error> {
-        &mut self,
-        address: u8,
-        read: &mut [u8],
-        restart: bool,
-        check_timeout: impl Fn() -> Result<(), Error>,
-    ) -> Result<(), Error> {
        let completed_chunks = read.len() / 255;
        let total_chunks = if completed_chunks * 255 == read.len() {
            completed_chunks
@@ -345,17 +232,17 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
            Stop::Automatic,
            last_chunk_idx != 0,
            restart,
-            &check_timeout,
+            timeout,
        )?;
        for (number, chunk) in read.chunks_mut(255).enumerate() {
            if number != 0 {
-                Self::master_continue(chunk.len(), number != last_chunk_idx, &check_timeout)?;
+                Self::master_continue(chunk.len(), number != last_chunk_idx, timeout)?;
            }
            for byte in chunk {
                // Wait until we have received something
-                self.wait_rxne(&check_timeout)?;
+                self.wait_rxne(timeout)?;
                *byte = T::regs().rxdr().read().rxdata();
            }
@@ -363,13 +250,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
        Ok(())
    }
-    fn write_internal(
+    fn write_internal(&mut self, address: u8, write: &[u8], send_stop: bool, timeout: Timeout) -> Result<(), Error> {
-        &mut self,
-        address: u8,
-        write: &[u8],
-        send_stop: bool,
-        check_timeout: impl Fn() -> Result<(), Error>,
-    ) -> Result<(), Error> {
        let completed_chunks = write.len() / 255;
        let total_chunks = if completed_chunks * 255 == write.len() {
            completed_chunks
@@ -386,7 +267,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
            write.len().min(255),
            Stop::Software,
            last_chunk_idx != 0,
-            &check_timeout,
+            timeout,
        ) {
            if send_stop {
                self.master_stop();
@@ -396,14 +277,14 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
        for (number, chunk) in write.chunks(255).enumerate() {
            if number != 0 {
-                Self::master_continue(chunk.len(), number != last_chunk_idx, &check_timeout)?;
+                Self::master_continue(chunk.len(), number != last_chunk_idx, timeout)?;
            }
            for byte in chunk {
                // Wait until we are allowed to send data
                // (START has been ACKed or last byte when
                // through)
-                if let Err(err) = self.wait_txe(&check_timeout) {
+                if let Err(err) = self.wait_txe(timeout) {
                    if send_stop {
                        self.master_stop();
                    }
@@ -414,7 +295,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
            }
        }
        // Wait until the write finishes
-        let result = self.wait_tc(&check_timeout);
+        let result = self.wait_tc(timeout);
        if send_stop {
            self.master_stop();
        }
@@ -427,7 +308,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
        write: &[u8],
        first_slice: bool,
        last_slice: bool,
-        check_timeout: impl Fn() -> Result<(), Error>,
+        timeout: Timeout,
    ) -> Result<(), Error>
    where
        TXDMA: crate::i2c::TxDma<T>,
@@ -473,10 +354,10 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
                        total_len.min(255),
                        Stop::Software,
                        (total_len > 255) || !last_slice,
-                        &check_timeout,
+                        timeout,
                    )?;
                } else {
-                    Self::master_continue(total_len.min(255), (total_len > 255) || !last_slice, &check_timeout)?;
+                    Self::master_continue(total_len.min(255), (total_len > 255) || !last_slice, timeout)?;
                    T::regs().cr1().modify(|w| w.set_tcie(true));
                }
            } else if !(isr.tcr() || isr.tc()) {
@@ -487,7 +368,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
            } else {
                let last_piece = (remaining_len <= 255) && last_slice;
-                if let Err(e) = Self::master_continue(remaining_len.min(255), !last_piece, &check_timeout) {
+                if let Err(e) = Self::master_continue(remaining_len.min(255), !last_piece, timeout) {
                    return Poll::Ready(Err(e));
                }
                T::regs().cr1().modify(|w| w.set_tcie(true));
@@ -502,7 +383,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
        if last_slice {
            // This should be done already
-            self.wait_tc(&check_timeout)?;
+            self.wait_tc(timeout)?;
            self.master_stop();
        }
@@ -516,7 +397,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
        address: u8,
        buffer: &mut [u8],
        restart: bool,
-        check_timeout: impl Fn() -> Result<(), Error>,
+        timeout: Timeout,
    ) -> Result<(), Error>
    where
        RXDMA: crate::i2c::RxDma<T>,
@@ -558,7 +439,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
                    Stop::Software,
                    total_len > 255,
                    restart,
-                    &check_timeout,
+                    timeout,
                )?;
            } else if !(isr.tcr() || isr.tc()) {
                // poll_fn was woken without an interrupt present
@@ -568,7 +449,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
            } else {
                let last_piece = remaining_len <= 255;
-                if let Err(e) = Self::master_continue(remaining_len.min(255), !last_piece, &check_timeout) {
+                if let Err(e) = Self::master_continue(remaining_len.min(255), !last_piece, timeout) {
                    return Poll::Ready(Err(e));
                }
                T::regs().cr1().modify(|w| w.set_tcie(true));
@@ -582,7 +463,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
        dma_transfer.await;
        // This should be done already
-        self.wait_tc(&check_timeout)?;
+        self.wait_tc(timeout)?;
        self.master_stop();
        drop(on_drop);
@@ -592,69 +473,31 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
    // =========================
    //  Async public API
-    #[cfg(feature = "time")]
-    pub async fn write(&mut self, address: u8, write: &[u8]) -> Result<(), Error>
-    where
-        TXDMA: crate::i2c::TxDma<T>,
-    {
-        if write.is_empty() {
-            self.write_internal(address, write, true, timeout_fn(self.timeout))
-        } else {
-            embassy_time::with_timeout(
-                self.timeout,
-                self.write_dma_internal(address, write, true, true, timeout_fn(self.timeout)),
-            )
-            .await
-            .unwrap_or(Err(Error::Timeout))
-        }
-    }
-    #[cfg(not(feature = "time"))]
+    /// Write.
    pub async fn write(&mut self, address: u8, write: &[u8]) -> Result<(), Error>
    where
        TXDMA: crate::i2c::TxDma<T>,
    {
+        let timeout = self.timeout();
        if write.is_empty() {
-            self.write_internal(address, write, true, no_timeout_fn())
+            self.write_internal(address, write, true, timeout)
        } else {
-            self.write_dma_internal(address, write, true, true, no_timeout_fn())
+            timeout
+                .with(self.write_dma_internal(address, write, true, true, timeout))
                .await
        }
    }
-    #[cfg(feature = "time")]
+    /// Write multiple buffers.
+    ///
+    /// The buffers are concatenated in a single write transaction.
    pub async fn write_vectored(&mut self, address: u8, write: &[&[u8]]) -> Result<(), Error>
    where
        TXDMA: crate::i2c::TxDma<T>,
    {
-        if write.is_empty() {
+        let timeout = self.timeout();
-            return Err(Error::ZeroLengthTransfer);
-        }
-        let mut iter = write.iter();
-        let mut first = true;
-        let mut current = iter.next();
-        while let Some(c) = current {
-            let next = iter.next();
-            let is_last = next.is_none();
-            embassy_time::with_timeout(
-                self.timeout,
-                self.write_dma_internal(address, c, first, is_last, timeout_fn(self.timeout)),
-            )
-            .await
-            .unwrap_or(Err(Error::Timeout))?;
-            first = false;
-            current = next;
-        }
-        Ok(())
-    }
-    #[cfg(not(feature = "time"))]
-    pub async fn write_vectored(&mut self, address: u8, write: &[&[u8]]) -> Result<(), Error>
-    where
-        TXDMA: crate::i2c::TxDma<T>,
-    {
        if write.is_empty() {
            return Err(Error::ZeroLengthTransfer);
        }
@@ -666,95 +509,49 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
            let next = iter.next();
            let is_last = next.is_none();
-            self.write_dma_internal(address, c, first, is_last, no_timeout_fn())
+            let fut = self.write_dma_internal(address, c, first, is_last, timeout);
-                .await?;
+            timeout.with(fut).await?;
            first = false;
            current = next;
        }
        Ok(())
    }
-    #[cfg(feature = "time")]
+    /// Read.
    pub async fn read(&mut self, address: u8, buffer: &mut [u8]) -> Result<(), Error>
    where
        RXDMA: crate::i2c::RxDma<T>,
    {
-        if buffer.is_empty() {
+        let timeout = self.timeout();
-            self.read_internal(address, buffer, false, timeout_fn(self.timeout))
-        } else {
-            embassy_time::with_timeout(
-                self.timeout,
-                self.read_dma_internal(address, buffer, false, timeout_fn(self.timeout)),
-            )
-            .await
-            .unwrap_or(Err(Error::Timeout))
-        }
-    }
-    #[cfg(not(feature = "time"))]
-    pub async fn read(&mut self, address: u8, buffer: &mut [u8]) -> Result<(), Error>
-    where
-        RXDMA: crate::i2c::RxDma<T>,
-    {
        if buffer.is_empty() {
-            self.read_internal(address, buffer, false, no_timeout_fn())
+            self.read_internal(address, buffer, false, timeout)
        } else {
-            self.read_dma_internal(address, buffer, false, no_timeout_fn()).await
+            let fut = self.read_dma_internal(address, buffer, false, timeout);
+            timeout.with(fut).await
        }
    }
-    #[cfg(feature = "time")]
+    /// Write, restart, read.
    pub async fn write_read(&mut self, address: u8, write: &[u8], read: &mut [u8]) -> Result<(), Error>
    where
        TXDMA: super::TxDma<T>,
        RXDMA: super::RxDma<T>,
    {
-        let start_instant = Instant::now();
+        let timeout = self.timeout();
-        let check_timeout = timeout_fn(self.timeout);
-        if write.is_empty() {
-            self.write_internal(address, write, false, &check_timeout)?;
-        } else {
-            embassy_time::with_timeout(
-                self.timeout,
-                self.write_dma_internal(address, write, true, true, &check_timeout),
-            )
-            .await
-            .unwrap_or(Err(Error::Timeout))?;
-        }
-        let time_left_until_timeout = self.timeout - Instant::now().duration_since(start_instant);
-        if read.is_empty() {
-            self.read_internal(address, read, true, &check_timeout)?;
-        } else {
-            embassy_time::with_timeout(
-                time_left_until_timeout,
-                self.read_dma_internal(address, read, true, &check_timeout),
-            )
-            .await
-            .unwrap_or(Err(Error::Timeout))?;
-        }
-        Ok(())
-    }
-    #[cfg(not(feature = "time"))]
-    pub async fn write_read(&mut self, address: u8, write: &[u8], read: &mut [u8]) -> Result<(), Error>
-    where
-        TXDMA: super::TxDma<T>,
-        RXDMA: super::RxDma<T>,
-    {
-        let no_timeout = no_timeout_fn();
        if write.is_empty() {
-            self.write_internal(address, write, false, &no_timeout)?;
+            self.write_internal(address, write, false, timeout)?;
        } else {
-            self.write_dma_internal(address, write, true, true, &no_timeout).await?;
+            let fut = self.write_dma_internal(address, write, true, true, timeout);
+            timeout.with(fut).await?;
        }
        if read.is_empty() {
-            self.read_internal(address, read, true, &no_timeout)?;
+            self.read_internal(address, read, true, timeout)?;
        } else {
-            self.read_dma_internal(address, read, true, &no_timeout).await?;
+            let fut = self.read_dma_internal(address, read, true, timeout);
+            timeout.with(fut).await?;
        }
        Ok(())
@@ -763,105 +560,35 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
    // =========================
    //  Blocking public API
-    #[cfg(feature = "time")]
+    /// Blocking read.
-    pub fn blocking_read_timeout(&mut self, address: u8, read: &mut [u8], timeout: Duration) -> Result<(), Error> {
-        self.read_internal(address, read, false, timeout_fn(timeout))
-        // Automatic Stop
-    }
-    #[cfg(not(feature = "time"))]
-    pub fn blocking_read_timeout(
-        &mut self,
-        address: u8,
-        read: &mut [u8],
-        check_timeout: impl Fn() -> Result<(), Error>,
-    ) -> Result<(), Error> {
-        self.read_internal(address, read, false, check_timeout)
-        // Automatic Stop
-    }
-    #[cfg(feature = "time")]
-    pub fn blocking_read(&mut self, address: u8, read: &mut [u8]) -> Result<(), Error> {
-        self.blocking_read_timeout(address, read, self.timeout)
-    }
-    #[cfg(not(feature = "time"))]
    pub fn blocking_read(&mut self, address: u8, read: &mut [u8]) -> Result<(), Error> {
-        self.blocking_read_timeout(address, read, || Ok(()))
+        self.read_internal(address, read, false, self.timeout())
-    }
-    #[cfg(feature = "time")]
-    pub fn blocking_write_timeout(&mut self, address: u8, write: &[u8], timeout: Duration) -> Result<(), Error> {
-        self.write_internal(address, write, true, timeout_fn(timeout))
-    }
-    #[cfg(not(feature = "time"))]
-    pub fn blocking_write_timeout(
-        &mut self,
-        address: u8,
-        write: &[u8],
-        check_timeout: impl Fn() -> Result<(), Error>,
-    ) -> Result<(), Error> {
-        self.write_internal(address, write, true, check_timeout)
-    }
-    #[cfg(feature = "time")]
-    pub fn blocking_write(&mut self, address: u8, write: &[u8]) -> Result<(), Error> {
-        self.blocking_write_timeout(address, write, self.timeout)
-    }
-    #[cfg(not(feature = "time"))]
-    pub fn blocking_write(&mut self, address: u8, write: &[u8]) -> Result<(), Error> {
-        self.blocking_write_timeout(address, write, || Ok(()))
-    }
-    #[cfg(feature = "time")]
-    pub fn blocking_write_read_timeout(
-        &mut self,
-        address: u8,
-        write: &[u8],
-        read: &mut [u8],
-        timeout: Duration,
-    ) -> Result<(), Error> {
-        let check_timeout = timeout_fn(timeout);
-        self.write_internal(address, write, false, &check_timeout)?;
-        self.read_internal(address, read, true, &check_timeout)
        // Automatic Stop
    }
-    #[cfg(not(feature = "time"))]
+    /// Blocking write.
-    pub fn blocking_write_read_timeout(
+    pub fn blocking_write(&mut self, address: u8, write: &[u8]) -> Result<(), Error> {
-        &mut self,
+        self.write_internal(address, write, true, self.timeout())
-        address: u8,
-        write: &[u8],
-        read: &mut [u8],
-        check_timeout: impl Fn() -> Result<(), Error>,
-    ) -> Result<(), Error> {
-        self.write_internal(address, write, false, &check_timeout)?;
-        self.read_internal(address, read, true, &check_timeout)
-        // Automatic Stop
-    }
-    #[cfg(feature = "time")]
-    pub fn blocking_write_read(&mut self, address: u8, write: &[u8], read: &mut [u8]) -> Result<(), Error> {
-        self.blocking_write_read_timeout(address, write, read, self.timeout)
    }
-    #[cfg(not(feature = "time"))]
+    /// Blocking write, restart, read.
    pub fn blocking_write_read(&mut self, address: u8, write: &[u8], read: &mut [u8]) -> Result<(), Error> {
-        self.blocking_write_read_timeout(address, write, read, || Ok(()))
+        let timeout = self.timeout();
+        self.write_internal(address, write, false, timeout)?;
+        self.read_internal(address, read, true, timeout)
+        // Automatic Stop
    }
-    fn blocking_write_vectored_with_timeout(
+    /// Blocking write multiple buffers.
-        &mut self,
+    ///
-        address: u8,
+    /// The buffers are concatenated in a single write transaction.
-        write: &[&[u8]],
+    pub fn blocking_write_vectored(&mut self, address: u8, write: &[&[u8]]) -> Result<(), Error> {
-        check_timeout: impl Fn() -> Result<(), Error>,
-    ) -> Result<(), Error> {
        if write.is_empty() {
            return Err(Error::ZeroLengthTransfer);
        }
+        let timeout = self.timeout();
        let first_length = write[0].len();
        let last_slice_index = write.len() - 1;
@@ -870,7 +597,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
            first_length.min(255),
            Stop::Software,
            (first_length > 255) || (last_slice_index != 0),
-            &check_timeout,
+            timeout,
        ) {
            self.master_stop();
            return Err(err);
@@ -890,7 +617,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
                if let Err(err) = Self::master_continue(
                    slice_len.min(255),
                    (idx != last_slice_index) || (slice_len > 255),
-                    &check_timeout,
+                    timeout,
                ) {
                    self.master_stop();
                    return Err(err);
@@ -902,7 +629,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
                    if let Err(err) = Self::master_continue(
                        chunk.len(),
                        (number != last_chunk_idx) || (idx != last_slice_index),
-                        &check_timeout,
+                        timeout,
                    ) {
                        self.master_stop();
                        return Err(err);
@@ -913,7 +640,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
                    // Wait until we are allowed to send data
                    // (START has been ACKed or last byte when
                    // through)
-                    if let Err(err) = self.wait_txe(&check_timeout) {
+                    if let Err(err) = self.wait_txe(timeout) {
                        self.master_stop();
                        return Err(err);
                    }
@@ -925,41 +652,10 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
            }
        }
        // Wait until the write finishes
-        let result = self.wait_tc(&check_timeout);
+        let result = self.wait_tc(timeout);
        self.master_stop();
        result
    }
-    #[cfg(feature = "time")]
-    pub fn blocking_write_vectored_timeout(
-        &mut self,
-        address: u8,
-        write: &[&[u8]],
-        timeout: Duration,
-    ) -> Result<(), Error> {
-        let check_timeout = timeout_fn(timeout);
-        self.blocking_write_vectored_with_timeout(address, write, check_timeout)
-    }
-    #[cfg(not(feature = "time"))]
-    pub fn blocking_write_vectored_timeout(
-        &mut self,
-        address: u8,
-        write: &[&[u8]],
-        check_timeout: impl Fn() -> Result<(), Error>,
-    ) -> Result<(), Error> {
-        self.blocking_write_vectored_with_timeout(address, write, check_timeout)
-    }
-    #[cfg(feature = "time")]
-    pub fn blocking_write_vectored(&mut self, address: u8, write: &[&[u8]]) -> Result<(), Error> {
-        self.blocking_write_vectored_timeout(address, write, self.timeout)
-    }
-    #[cfg(not(feature = "time"))]
-    pub fn blocking_write_vectored(&mut self, address: u8, write: &[&[u8]]) -> Result<(), Error> {
-        self.blocking_write_vectored_timeout(address, write, || Ok(()))
-    }
 }
 impl<'d, T: Instance, TXDMA, RXDMA> Drop for I2c<'d, T, TXDMA, RXDMA> {
diff --git a/embassy-stm32/src/i2s.rs b/embassy-stm32/src/i2s.rs
index 67d40c479..1f85c0bc5 100644
--- a/embassy-stm32/src/i2s.rs
+++ b/embassy-stm32/src/i2s.rs
@@ -1,3 +1,4 @@
+//! Inter-IC Sound (I2S)
 use embassy_hal_internal::into_ref;
 use crate::gpio::sealed::{AFType, Pin as _};
@@ -8,30 +9,42 @@ use crate::spi::{Config as SpiConfig, *};
 use crate::time::Hertz;
 use crate::{Peripheral, PeripheralRef};
+/// I2S mode
 #[derive(Copy, Clone)]
 pub enum Mode {
+    /// Master mode
    Master,
+    /// Slave mode
    Slave,
 }
+/// I2S function
 #[derive(Copy, Clone)]
 pub enum Function {
+    /// Transmit audio data
    Transmit,
+    /// Receive audio data
    Receive,
 }
+/// I2C standard
 #[derive(Copy, Clone)]
 pub enum Standard {
+    /// Philips
    Philips,
+    /// Most significant bit first.
    MsbFirst,
+    /// Least significant bit first.
    LsbFirst,
+    /// PCM with long sync.
    PcmLongSync,
+    /// PCM with short sync.
    PcmShortSync,
 }
 impl Standard {
    #[cfg(any(spi_v1, spi_f1))]
-    pub const fn i2sstd(&self) -> vals::I2sstd {
+    const fn i2sstd(&self) -> vals::I2sstd {
        match self {
            Standard::Philips => vals::I2sstd::PHILIPS,
            Standard::MsbFirst => vals::I2sstd::MSB,
@@ -42,7 +55,7 @@ impl Standard {
    }
    #[cfg(any(spi_v1, spi_f1))]
-    pub const fn pcmsync(&self) -> vals::Pcmsync {
+    const fn pcmsync(&self) -> vals::Pcmsync {
        match self {
            Standard::PcmLongSync => vals::Pcmsync::LONG,
            _ => vals::Pcmsync::SHORT,
@@ -50,6 +63,7 @@ impl Standard {
    }
 }
+/// I2S data format.
 #[derive(Copy, Clone)]
 pub enum Format {
    /// 16 bit data length on 16 bit wide channel
@@ -64,7 +78,7 @@ pub enum Format {
 impl Format {
    #[cfg(any(spi_v1, spi_f1))]
-    pub const fn datlen(&self) -> vals::Datlen {
+    const fn datlen(&self) -> vals::Datlen {
        match self {
            Format::Data16Channel16 => vals::Datlen::SIXTEENBIT,
            Format::Data16Channel32 => vals::Datlen::SIXTEENBIT,
@@ -74,7 +88,7 @@ impl Format {
    }
    #[cfg(any(spi_v1, spi_f1))]
-    pub const fn chlen(&self) -> vals::Chlen {
+    const fn chlen(&self) -> vals::Chlen {
        match self {
            Format::Data16Channel16 => vals::Chlen::SIXTEENBIT,
            Format::Data16Channel32 => vals::Chlen::THIRTYTWOBIT,
@@ -84,15 +98,18 @@ impl Format {
    }
 }
+/// Clock polarity
 #[derive(Copy, Clone)]
 pub enum ClockPolarity {
+    /// Low on idle.
    IdleLow,
+    /// High on idle.
    IdleHigh,
 }
 impl ClockPolarity {
    #[cfg(any(spi_v1, spi_f1))]
-    pub const fn ckpol(&self) -> vals::Ckpol {
+    const fn ckpol(&self) -> vals::Ckpol {
        match self {
            ClockPolarity::IdleHigh => vals::Ckpol::IDLEHIGH,
            ClockPolarity::IdleLow => vals::Ckpol::IDLELOW,
@@ -109,11 +126,17 @@ impl ClockPolarity {
 #[non_exhaustive]
 #[derive(Copy, Clone)]
 pub struct Config {
+    /// Mode
    pub mode: Mode,
+    /// Function (transmit, receive)
    pub function: Function,
+    /// Which I2S standard to use.
    pub standard: Standard,
+    /// Data format.
    pub format: Format,
+    /// Clock polarity.
    pub clock_polarity: ClockPolarity,
+    /// True to eanble master clock output from this instance.
    pub master_clock: bool,
 }
@@ -130,6 +153,7 @@ impl Default for Config {
    }
 }
+/// I2S driver.
 pub struct I2S<'d, T: Instance, Tx, Rx> {
    _peri: Spi<'d, T, Tx, Rx>,
    sd: Option<PeripheralRef<'d, AnyPin>>,
@@ -242,6 +266,7 @@ impl<'d, T: Instance, Tx, Rx> I2S<'d, T, Tx, Rx> {
        }
    }
+    /// Write audio data.
    pub async fn write<W: Word>(&mut self, data: &[W]) -> Result<(), Error>
    where
        Tx: TxDma<T>,
@@ -249,6 +274,7 @@ impl<'d, T: Instance, Tx, Rx> I2S<'d, T, Tx, Rx> {
        self._peri.write(data).await
    }
+    /// Read audio data.
    pub async fn read<W: Word>(&mut self, data: &mut [W]) -> Result<(), Error>
    where
        Tx: TxDma<T>,
diff --git a/embassy-stm32/src/ipcc.rs b/embassy-stm32/src/ipcc.rs
index 4006dee19..663a7f59d 100644
--- a/embassy-stm32/src/ipcc.rs
+++ b/embassy-stm32/src/ipcc.rs
@@ -1,3 +1,5 @@
+//! Inter-Process Communication Controller (IPCC)
 use core::future::poll_fn;
 use core::sync::atomic::{compiler_fence, Ordering};
 use core::task::Poll;
@@ -41,6 +43,7 @@ impl interrupt::typelevel::Handler<interrupt::typelevel::IPCC_C1_RX> for Receive
    }
 }
+/// TX interrupt handler.
 pub struct TransmitInterruptHandler {}
 impl interrupt::typelevel::Handler<interrupt::typelevel::IPCC_C1_TX> for TransmitInterruptHandler {
@@ -72,6 +75,7 @@ impl interrupt::typelevel::Handler<interrupt::typelevel::IPCC_C1_TX> for Transmi
    }
 }
+/// IPCC config.
 #[non_exhaustive]
 #[derive(Clone, Copy, Default)]
 pub struct Config {
@@ -79,6 +83,8 @@ pub struct Config {
    // reserved for future use
 }
+/// Channel.
+#[allow(missing_docs)]
 #[derive(Debug, Clone, Copy)]
 #[repr(C)]
 pub enum IpccChannel {
@@ -90,9 +96,11 @@ pub enum IpccChannel {
    Channel6 = 5,
 }
+/// IPCC driver.
 pub struct Ipcc;
 impl Ipcc {
+    /// Enable IPCC.
    pub fn enable(_config: Config) {
        IPCC::enable_and_reset();
        IPCC::set_cpu2(true);
diff --git a/embassy-stm32/src/lib.rs b/embassy-stm32/src/lib.rs
index 5d9b4e6a0..f10e9d50d 100644
--- a/embassy-stm32/src/lib.rs
+++ b/embassy-stm32/src/lib.rs
@@ -1,5 +1,6 @@
 #![cfg_attr(not(test), no_std)]
 #![allow(async_fn_in_trait)]
+#![warn(missing_docs)]
 //! ## Feature flags
 #![doc = document_features::document_features!(feature_label = r#"<span class="stab portability"><code>{feature}</code></span>"#)]
@@ -79,6 +80,7 @@ pub(crate) mod _generated {
    #![allow(dead_code)]
    #![allow(unused_imports)]
    #![allow(non_snake_case)]
+    #![allow(missing_docs)]
    include!(concat!(env!("OUT_DIR"), "/_generated.rs"));
 }
@@ -149,15 +151,33 @@ use crate::interrupt::Priority;
 pub use crate::pac::NVIC_PRIO_BITS;
 use crate::rcc::sealed::RccPeripheral;
+/// `embassy-stm32` global configuration.
 #[non_exhaustive]
 pub struct Config {
+    /// RCC config.
    pub rcc: rcc::Config,
+    /// Enable debug during sleep.
+    ///
+    /// May incrase power consumption. Defaults to true.
    #[cfg(dbgmcu)]
    pub enable_debug_during_sleep: bool,
+    /// BDMA interrupt priority.
+    ///
+    /// Defaults to P0 (highest).
    #[cfg(bdma)]
    pub bdma_interrupt_priority: Priority,
+    /// DMA interrupt priority.
+    ///
+    /// Defaults to P0 (highest).
    #[cfg(dma)]
    pub dma_interrupt_priority: Priority,
+    /// GPDMA interrupt priority.
+    ///
+    /// Defaults to P0 (highest).
    #[cfg(gpdma)]
    pub gpdma_interrupt_priority: Priority,
 }
@@ -178,38 +198,40 @@ impl Default for Config {
    }
 }
-/// Initialize embassy.
+/// Initialize the `embassy-stm32` HAL with the provided configuration.
+///
+/// This returns the peripheral singletons that can be used for creating drivers.
+///
+/// This should only be called once at startup, otherwise it panics.
 pub fn init(config: Config) -> Peripherals {
    critical_section::with(|cs| {
        let p = Peripherals::take_with_cs(cs);
        #[cfg(dbgmcu)]
-        if config.enable_debug_during_sleep {
+        crate::pac::DBGMCU.cr().modify(|cr| {
-            crate::pac::DBGMCU.cr().modify(|cr| {
+            #[cfg(any(dbgmcu_f0, dbgmcu_c0, dbgmcu_g0, dbgmcu_u5, dbgmcu_wba))]
-                #[cfg(any(dbgmcu_f0, dbgmcu_c0, dbgmcu_g0, dbgmcu_u5, dbgmcu_wba))]
+            {
-                {
+                cr.set_dbg_stop(config.enable_debug_during_sleep);
-                    cr.set_dbg_stop(true);
+                cr.set_dbg_standby(config.enable_debug_during_sleep);
-                    cr.set_dbg_standby(true);
+            }
-                }
+            #[cfg(any(
-                #[cfg(any(
+                dbgmcu_f1, dbgmcu_f2, dbgmcu_f3, dbgmcu_f4, dbgmcu_f7, dbgmcu_g4, dbgmcu_f7, dbgmcu_l0, dbgmcu_l1,
-                    dbgmcu_f1, dbgmcu_f2, dbgmcu_f3, dbgmcu_f4, dbgmcu_f7, dbgmcu_g4, dbgmcu_f7, dbgmcu_l0, dbgmcu_l1,
+                dbgmcu_l4, dbgmcu_wb, dbgmcu_wl
-                    dbgmcu_l4, dbgmcu_wb, dbgmcu_wl
+            ))]
-                ))]
+            {
-                {
+                cr.set_dbg_sleep(config.enable_debug_during_sleep);
-                    cr.set_dbg_sleep(true);
+                cr.set_dbg_stop(config.enable_debug_during_sleep);
-                    cr.set_dbg_stop(true);
+                cr.set_dbg_standby(config.enable_debug_during_sleep);
-                    cr.set_dbg_standby(true);
+            }
-                }
+            #[cfg(dbgmcu_h7)]
-                #[cfg(dbgmcu_h7)]
+            {
-                {
+                cr.set_d1dbgcken(config.enable_debug_during_sleep);
-                    cr.set_d1dbgcken(true);
+                cr.set_d3dbgcken(config.enable_debug_during_sleep);
-                    cr.set_d3dbgcken(true);
+                cr.set_dbgsleep_d1(config.enable_debug_during_sleep);
-                    cr.set_dbgsleep_d1(true);
+                cr.set_dbgstby_d1(config.enable_debug_during_sleep);
-                    cr.set_dbgstby_d1(true);
+                cr.set_dbgstop_d1(config.enable_debug_during_sleep);
-                    cr.set_dbgstop_d1(true);
+            }
-                }
+        });
-            });
-        }
        #[cfg(not(any(stm32f1, stm32wb, stm32wl)))]
        peripherals::SYSCFG::enable_and_reset_with_cs(cs);
diff --git a/embassy-stm32/src/low_power.rs b/embassy-stm32/src/low_power.rs
index 20d8f9045..4fab8dae4 100644
--- a/embassy-stm32/src/low_power.rs
+++ b/embassy-stm32/src/low_power.rs
@@ -1,50 +1,54 @@
-/// The STM32 line of microcontrollers support various deep-sleep modes which exploit clock-gating
+//! Low-power support.
-/// to reduce power consumption. `embassy-stm32` provides a low-power executor, [`Executor`] which
+//!
-/// can use knowledge of which peripherals are currently blocked upon to transparently and safely
+//! The STM32 line of microcontrollers support various deep-sleep modes which exploit clock-gating
-/// enter such low-power modes (currently, only `STOP2`) when idle.
+//! to reduce power consumption. `embassy-stm32` provides a low-power executor, [`Executor`] which
-///
+//! can use knowledge of which peripherals are currently blocked upon to transparently and safely
-/// The executor determines which peripherals are active by their RCC state; consequently,
+//! enter such low-power modes (currently, only `STOP2`) when idle.
-/// low-power states can only be entered if all peripherals have been `drop`'d. There are a few
+//!
-/// exceptions to this rule:
+//! The executor determines which peripherals are active by their RCC state; consequently,
-///
+//! low-power states can only be entered if all peripherals have been `drop`'d. There are a few
-///  * `GPIO`
+//! exceptions to this rule:
-///  * `RCC`
+//!
-///
+//!  * `GPIO`
-/// Since entering and leaving low-power modes typically incurs a significant latency, the
+//!  * `RCC`
-/// low-power executor will only attempt to enter when the next timer event is at least
+//!
-/// [`time_driver::MIN_STOP_PAUSE`] in the future.
+//! Since entering and leaving low-power modes typically incurs a significant latency, the
-///
+//! low-power executor will only attempt to enter when the next timer event is at least
-/// Currently there is no macro analogous to `embassy_executor::main` for this executor;
+//! [`time_driver::MIN_STOP_PAUSE`] in the future.
-/// consequently one must define their entrypoint manually. Moveover, you must relinquish control
+//!
-/// of the `RTC` peripheral to the executor. This will typically look like
+//! Currently there is no macro analogous to `embassy_executor::main` for this executor;
-///
+//! consequently one must define their entrypoint manually. Moveover, you must relinquish control
-/// ```rust,no_run
+//! of the `RTC` peripheral to the executor. This will typically look like
-/// use embassy_executor::Spawner;
+//!
-/// use embassy_stm32::low_power::Executor;
+//! ```rust,no_run
-/// use embassy_stm32::rtc::{Rtc, RtcConfig};
+//! use embassy_executor::Spawner;
-/// use static_cell::make_static;
+//! use embassy_stm32::low_power::Executor;
-///
+//! use embassy_stm32::rtc::{Rtc, RtcConfig};
-/// #[cortex_m_rt::entry]
+//! use static_cell::StaticCell;
-/// fn main() -> ! {
+//!
-///     Executor::take().run(|spawner| {
+//! #[cortex_m_rt::entry]
-///         unwrap!(spawner.spawn(async_main(spawner)));
+//! fn main() -> ! {
-///     });
+//!     Executor::take().run(|spawner| {
-/// }
+//!         unwrap!(spawner.spawn(async_main(spawner)));
-///
+//!     });
-/// #[embassy_executor::task]
+//! }
-/// async fn async_main(spawner: Spawner) {
+//!
-///     // initialize the platform...
+//! #[embassy_executor::task]
-///     let mut config = embassy_stm32::Config::default();
+//! async fn async_main(spawner: Spawner) {
-///     let p = embassy_stm32::init(config);
+//!     // initialize the platform...
-///
+//!     let mut config = embassy_stm32::Config::default();
-///     // give the RTC to the executor...
+//!     let p = embassy_stm32::init(config);
-///     let mut rtc = Rtc::new(p.RTC, RtcConfig::default());
+//!
-///     let rtc = make_static!(rtc);
+//!     // give the RTC to the executor...
-///     embassy_stm32::low_power::stop_with_rtc(rtc);
+//!     let mut rtc = Rtc::new(p.RTC, RtcConfig::default());
-///
+//!     static RTC: StaticCell<Rtc> = StaticCell::new();
-///     // your application here...
+//!     let rtc = RTC.init(rtc);
-/// }
+//!     embassy_stm32::low_power::stop_with_rtc(rtc);
-/// ```
+//!
+//!     // your application here...
+//! }
+//! ```
 use core::arch::asm;
 use core::marker::PhantomData;
 use core::sync::atomic::{compiler_fence, Ordering};
@@ -64,6 +68,7 @@ static mut EXECUTOR: Option<Executor> = None;
 foreach_interrupt! {
    (RTC, rtc, $block:ident, WKUP, $irq:ident) => {
        #[interrupt]
+        #[allow(non_snake_case)]
        unsafe fn $irq() {
            EXECUTOR.as_mut().unwrap().on_wakeup_irq();
        }
@@ -75,10 +80,15 @@ pub(crate) unsafe fn on_wakeup_irq() {
    EXECUTOR.as_mut().unwrap().on_wakeup_irq();
 }
+/// Configure STOP mode with RTC.
 pub fn stop_with_rtc(rtc: &'static Rtc) {
    unsafe { EXECUTOR.as_mut().unwrap() }.stop_with_rtc(rtc)
 }
+/// Get whether the core is ready to enter the given stop mode.
+///
+/// This will return false if some peripheral driver is in use that
+/// prevents entering the given stop mode.
 pub fn stop_ready(stop_mode: StopMode) -> bool {
    match unsafe { EXECUTOR.as_mut().unwrap() }.stop_mode() {
        Some(StopMode::Stop2) => true,
@@ -87,10 +97,13 @@ pub fn stop_ready(stop_mode: StopMode) -> bool {
    }
 }
+/// Available stop modes.
 #[non_exhaustive]
 #[derive(PartialEq)]
 pub enum StopMode {
+    /// STOP 1
    Stop1,
+    /// STOP 2
    Stop2,
 }
diff --git a/embassy-stm32/src/opamp.rs b/embassy-stm32/src/opamp.rs
index e1eb031d1..df8a78bcc 100644
--- a/embassy-stm32/src/opamp.rs
+++ b/embassy-stm32/src/opamp.rs
@@ -1,9 +1,12 @@
+//! Operational Amplifier (OPAMP)
 #![macro_use]
 use embassy_hal_internal::{into_ref, PeripheralRef};
 use crate::Peripheral;
+/// Gain
+#[allow(missing_docs)]
 #[derive(Clone, Copy)]
 pub enum OpAmpGain {
    Mul1,
@@ -13,6 +16,8 @@ pub enum OpAmpGain {
    Mul16,
 }
+/// Speed
+#[allow(missing_docs)]
 #[derive(Clone, Copy)]
 pub enum OpAmpSpeed {
    Normal,
@@ -180,6 +185,7 @@ impl<'d, T: Instance> Drop for OpAmpInternalOutput<'d, T> {
    }
 }
+/// Opamp instance trait.
 pub trait Instance: sealed::Instance + 'static {}
 pub(crate) mod sealed {
@@ -198,8 +204,11 @@ pub(crate) mod sealed {
    pub trait OutputPin<T: Instance> {}
 }
+/// Non-inverting pin trait.
 pub trait NonInvertingPin<T: Instance>: sealed::NonInvertingPin<T> {}
+/// Inverting pin trait.
 pub trait InvertingPin<T: Instance>: sealed::InvertingPin<T> {}
+/// Output pin trait.
 pub trait OutputPin<T: Instance>: sealed::OutputPin<T> {}
 macro_rules! impl_opamp_external_output {
diff --git a/embassy-stm32/src/qspi/enums.rs b/embassy-stm32/src/qspi/enums.rs
index 0412d991a..ecade9b1a 100644
--- a/embassy-stm32/src/qspi/enums.rs
+++ b/embassy-stm32/src/qspi/enums.rs
@@ -1,3 +1,5 @@
+//! Enums used in QSPI configuration.
 #[allow(dead_code)]
 #[derive(Copy, Clone)]
 pub(crate) enum QspiMode {
@@ -18,12 +20,17 @@ impl Into<u8> for QspiMode {
    }
 }
+/// QSPI lane width
 #[allow(dead_code)]
 #[derive(Copy, Clone)]
 pub enum QspiWidth {
+    /// None
    NONE,
+    /// Single lane
    SING,
+    /// Dual lanes
    DUAL,
+    /// Quad lanes
    QUAD,
 }
@@ -38,10 +45,13 @@ impl Into<u8> for QspiWidth {
    }
 }
+/// Flash bank selection
 #[allow(dead_code)]
 #[derive(Copy, Clone)]
 pub enum FlashSelection {
+    /// Bank 1
    Flash1,
+    /// Bank 2
    Flash2,
 }
@@ -54,6 +64,8 @@ impl Into<bool> for FlashSelection {
    }
 }
+/// QSPI memory size.
+#[allow(missing_docs)]
 #[derive(Copy, Clone)]
 pub enum MemorySize {
    _1KiB,
@@ -113,11 +125,16 @@ impl Into<u8> for MemorySize {
    }
 }
+/// QSPI Address size
 #[derive(Copy, Clone)]
 pub enum AddressSize {
+    /// 8-bit address
    _8Bit,
+    /// 16-bit address
    _16Bit,
+    /// 24-bit address
    _24bit,
+    /// 32-bit address
    _32bit,
 }
@@ -132,8 +149,10 @@ impl Into<u8> for AddressSize {
    }
 }
+/// Time the Chip Select line stays high.
+#[allow(missing_docs)]
 #[derive(Copy, Clone)]
-pub enum ChipSelectHightTime {
+pub enum ChipSelectHighTime {
    _1Cycle,
    _2Cycle,
    _3Cycle,
@@ -144,21 +163,23 @@ pub enum ChipSelectHightTime {
    _8Cycle,
 }
-impl Into<u8> for ChipSelectHightTime {
+impl Into<u8> for ChipSelectHighTime {
    fn into(self) -> u8 {
        match self {
-            ChipSelectHightTime::_1Cycle => 0,
+            ChipSelectHighTime::_1Cycle => 0,
-            ChipSelectHightTime::_2Cycle => 1,
+            ChipSelectHighTime::_2Cycle => 1,
-            ChipSelectHightTime::_3Cycle => 2,
+            ChipSelectHighTime::_3Cycle => 2,
-            ChipSelectHightTime::_4Cycle => 3,
+            ChipSelectHighTime::_4Cycle => 3,
-            ChipSelectHightTime::_5Cycle => 4,
+            ChipSelectHighTime::_5Cycle => 4,
-            ChipSelectHightTime::_6Cycle => 5,
+            ChipSelectHighTime::_6Cycle => 5,
-            ChipSelectHightTime::_7Cycle => 6,
+            ChipSelectHighTime::_7Cycle => 6,
-            ChipSelectHightTime::_8Cycle => 7,
+            ChipSelectHighTime::_8Cycle => 7,
        }
    }
 }
+/// FIFO threshold.
+#[allow(missing_docs)]
 #[derive(Copy, Clone)]
 pub enum FIFOThresholdLevel {
    _1Bytes,
@@ -234,6 +255,8 @@ impl Into<u8> for FIFOThresholdLevel {
    }
 }
+/// Dummy cycle count
+#[allow(missing_docs)]
 #[derive(Copy, Clone)]
 pub enum DummyCycles {
    _0,
diff --git a/embassy-stm32/src/qspi/mod.rs b/embassy-stm32/src/qspi/mod.rs
index 4b0e8ecef..8a709a89e 100644
--- a/embassy-stm32/src/qspi/mod.rs
+++ b/embassy-stm32/src/qspi/mod.rs
@@ -1,3 +1,5 @@
+//! Quad Serial Peripheral Interface (QSPI)
 #![macro_use]
 pub mod enums;
@@ -12,6 +14,7 @@ use crate::pac::quadspi::Quadspi as Regs;
 use crate::rcc::RccPeripheral;
 use crate::{peripherals, Peripheral};
+/// QSPI transfer configuration.
 pub struct TransferConfig {
    /// Instraction width (IMODE)
    pub iwidth: QspiWidth,
@@ -43,6 +46,7 @@ impl Default for TransferConfig {
    }
 }
+/// QSPI driver configuration.
 pub struct Config {
    /// Flash memory size representend as 2^[0-32], as reasonable minimum 1KiB(9) was chosen.
    /// If you need other value the whose predefined use `Other` variant.
@@ -54,7 +58,7 @@ pub struct Config {
    /// Number of bytes to trigger FIFO threshold flag.
    pub fifo_threshold: FIFOThresholdLevel,
    /// Minimum number of cycles that chip select must be high between issued commands
-    pub cs_high_time: ChipSelectHightTime,
+    pub cs_high_time: ChipSelectHighTime,
 }
 impl Default for Config {
@@ -64,11 +68,12 @@ impl Default for Config {
            address_size: AddressSize::_24bit,
            prescaler: 128,
            fifo_threshold: FIFOThresholdLevel::_17Bytes,
-            cs_high_time: ChipSelectHightTime::_5Cycle,
+            cs_high_time: ChipSelectHighTime::_5Cycle,
        }
    }
 }
+/// QSPI driver.
 #[allow(dead_code)]
 pub struct Qspi<'d, T: Instance, Dma> {
    _peri: PeripheralRef<'d, T>,
@@ -83,6 +88,7 @@ pub struct Qspi<'d, T: Instance, Dma> {
 }
 impl<'d, T: Instance, Dma> Qspi<'d, T, Dma> {
+    /// Create a new QSPI driver for bank 1.
    pub fn new_bk1(
        peri: impl Peripheral<P = T> + 'd,
        d0: impl Peripheral<P = impl BK1D0Pin<T>> + 'd,
@@ -119,10 +125,11 @@ impl<'d, T: Instance, Dma> Qspi<'d, T, Dma> {
            Some(nss.map_into()),
            dma,
            config,
-            FlashSelection::Flash2,
+            FlashSelection::Flash1,
        )
    }
+    /// Create a new QSPI driver for bank 2.
    pub fn new_bk2(
        peri: impl Peripheral<P = T> + 'd,
        d0: impl Peripheral<P = impl BK2D0Pin<T>> + 'd,
@@ -221,6 +228,7 @@ impl<'d, T: Instance, Dma> Qspi<'d, T, Dma> {
        }
    }
+    /// Do a QSPI command.
    pub fn command(&mut self, transaction: TransferConfig) {
        #[cfg(not(stm32h7))]
        T::REGS.cr().modify(|v| v.set_dmaen(false));
@@ -230,6 +238,7 @@ impl<'d, T: Instance, Dma> Qspi<'d, T, Dma> {
        T::REGS.fcr().modify(|v| v.set_ctcf(true));
    }
+    /// Blocking read data.
    pub fn blocking_read(&mut self, buf: &mut [u8], transaction: TransferConfig) {
        #[cfg(not(stm32h7))]
        T::REGS.cr().modify(|v| v.set_dmaen(false));
@@ -254,6 +263,7 @@ impl<'d, T: Instance, Dma> Qspi<'d, T, Dma> {
        T::REGS.fcr().modify(|v| v.set_ctcf(true));
    }
+    /// Blocking write data.
    pub fn blocking_write(&mut self, buf: &[u8], transaction: TransferConfig) {
        // STM32H7 does not have dmaen
        #[cfg(not(stm32h7))]
@@ -276,6 +286,7 @@ impl<'d, T: Instance, Dma> Qspi<'d, T, Dma> {
        T::REGS.fcr().modify(|v| v.set_ctcf(true));
    }
+    /// Blocking read data, using DMA.
    pub fn blocking_read_dma(&mut self, buf: &mut [u8], transaction: TransferConfig)
    where
        Dma: QuadDma<T>,
@@ -308,6 +319,7 @@ impl<'d, T: Instance, Dma> Qspi<'d, T, Dma> {
        transfer.blocking_wait();
    }
+    /// Blocking write data, using DMA.
    pub fn blocking_write_dma(&mut self, buf: &[u8], transaction: TransferConfig)
    where
        Dma: QuadDma<T>,
@@ -377,6 +389,7 @@ pub(crate) mod sealed {
    }
 }
+/// QSPI instance trait.
 pub trait Instance: Peripheral<P = Self> + sealed::Instance + RccPeripheral {}
 pin_trait!(SckPin, Instance);
diff --git a/embassy-stm32/src/rcc/h.rs b/embassy-stm32/src/rcc/h.rs
index 1889eb280..15b51a398 100644
--- a/embassy-stm32/src/rcc/h.rs
+++ b/embassy-stm32/src/rcc/h.rs
@@ -70,7 +70,9 @@ pub struct Pll {
    pub mul: PllMul,
    /// PLL P division factor. If None, PLL P output is disabled.
-    /// On PLL1, it must be even (in particular, it cannot be 1.)
+    /// On PLL1, it must be even for most series (in particular,
+    /// it cannot be 1 in series other than STM32H723/733,
+    /// STM32H725/735 and STM32H730.)
    pub divp: Option<PllDiv>,
    /// PLL Q division factor. If None, PLL Q output is disabled.
    pub divq: Option<PllDiv>,
@@ -476,7 +478,14 @@ pub(crate) unsafe fn init(config: Config) {
        VoltageScale::Scale2 => (Hertz(160_000_000), Hertz(160_000_000), Hertz(80_000_000)),
        VoltageScale::Scale3 => (Hertz(88_000_000), Hertz(88_000_000), Hertz(44_000_000)),
    };
-    #[cfg(all(stm32h7, not(pwr_h7rm0455)))]
+    #[cfg(pwr_h7rm0468)]
+    let (d1cpre_clk_max, hclk_max, pclk_max) = match config.voltage_scale {
+        VoltageScale::Scale0 => (Hertz(520_000_000), Hertz(275_000_000), Hertz(137_500_000)),
+        VoltageScale::Scale1 => (Hertz(400_000_000), Hertz(200_000_000), Hertz(100_000_000)),
+        VoltageScale::Scale2 => (Hertz(300_000_000), Hertz(150_000_000), Hertz(75_000_000)),
+        VoltageScale::Scale3 => (Hertz(170_000_000), Hertz(85_000_000), Hertz(42_500_000)),
+    };
+    #[cfg(all(stm32h7, not(any(pwr_h7rm0455, pwr_h7rm0468))))]
    let (d1cpre_clk_max, hclk_max, pclk_max) = match config.voltage_scale {
        VoltageScale::Scale0 => (Hertz(480_000_000), Hertz(240_000_000), Hertz(120_000_000)),
        VoltageScale::Scale1 => (Hertz(400_000_000), Hertz(200_000_000), Hertz(100_000_000)),
@@ -729,9 +738,12 @@ fn init_pll(num: usize, config: Option<Pll>, input: &PllInput) -> PllOutput {
    let p = config.divp.map(|div| {
        if num == 0 {
-            // on PLL1, DIVP must be even.
+            // on PLL1, DIVP must be even for most series.
            // The enum value is 1 less than the divider, so check it's odd.
+            #[cfg(not(pwr_h7rm0468))]
            assert!(div.to_bits() % 2 == 1);
+            #[cfg(pwr_h7rm0468)]
+            assert!(div.to_bits() % 2 == 1 || div.to_bits() == 0);
        }
        vco_clk / div
@@ -820,7 +832,7 @@ fn flash_setup(clk: Hertz, vos: VoltageScale) {
        _ => unreachable!(),
    };
-    #[cfg(flash_h7)]
+    #[cfg(all(flash_h7, not(pwr_h7rm0468)))]
    let (latency, wrhighfreq) = match (vos, clk.0) {
        // VOS 0 range VCORE 1.26V - 1.40V
        (VoltageScale::Scale0, ..=70_000_000) => (0, 0),
@@ -849,6 +861,30 @@ fn flash_setup(clk: Hertz, vos: VoltageScale) {
        _ => unreachable!(),
    };
+    // See RM0468 Rev 3 Table 16. FLASH recommended number of wait
+    // states and programming delay
+    #[cfg(all(flash_h7, pwr_h7rm0468))]
+    let (latency, wrhighfreq) = match (vos, clk.0) {
+        // VOS 0 range VCORE 1.26V - 1.40V
+        (VoltageScale::Scale0, ..=70_000_000) => (0, 0),
+        (VoltageScale::Scale0, ..=140_000_000) => (1, 1),
+        (VoltageScale::Scale0, ..=210_000_000) => (2, 2),
+        (VoltageScale::Scale0, ..=275_000_000) => (3, 3),
+        // VOS 1 range VCORE 1.15V - 1.26V
+        (VoltageScale::Scale1, ..=67_000_000) => (0, 0),
+        (VoltageScale::Scale1, ..=133_000_000) => (1, 1),
+        (VoltageScale::Scale1, ..=200_000_000) => (2, 2),
+        // VOS 2 range VCORE 1.05V - 1.15V
+        (VoltageScale::Scale2, ..=50_000_000) => (0, 0),
+        (VoltageScale::Scale2, ..=100_000_000) => (1, 1),
+        (VoltageScale::Scale2, ..=150_000_000) => (2, 2),
+        // VOS 3 range VCORE 0.95V - 1.05V
+        (VoltageScale::Scale3, ..=35_000_000) => (0, 0),
+        (VoltageScale::Scale3, ..=70_000_000) => (1, 1),
+        (VoltageScale::Scale3, ..=85_000_000) => (2, 2),
+        _ => unreachable!(),
+    };
    // See RM0455 Rev 10 Table 16. FLASH recommended number of wait
    // states and programming delay
    #[cfg(flash_h7ab)]
diff --git a/embassy-stm32/src/rcc/mod.rs b/embassy-stm32/src/rcc/mod.rs
index dc829a9ad..04a51110c 100644
--- a/embassy-stm32/src/rcc/mod.rs
+++ b/embassy-stm32/src/rcc/mod.rs
@@ -1,4 +1,7 @@
+//! Reset and Clock Control (RCC)
 #![macro_use]
+#![allow(missing_docs)] // TODO
 use core::mem::MaybeUninit;
diff --git a/embassy-stm32/src/rng.rs b/embassy-stm32/src/rng.rs
index 5e6922e9b..ca641f352 100644
--- a/embassy-stm32/src/rng.rs
+++ b/embassy-stm32/src/rng.rs
@@ -1,3 +1,4 @@
+//! Random Number Generator (RNG)
 #![macro_use]
 use core::future::poll_fn;
@@ -13,13 +14,19 @@ use crate::{interrupt, pac, peripherals, Peripheral};
 static RNG_WAKER: AtomicWaker = AtomicWaker::new();
+/// RNG error
 #[derive(Debug, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Error {
+    /// Seed error.
    SeedError,
+    /// Clock error. Double-check the RCC configuration,
+    /// see the Reference Manual for details on restrictions
+    /// on RNG clocks.
    ClockError,
 }
+/// RNG interrupt handler.
 pub struct InterruptHandler<T: Instance> {
    _phantom: PhantomData<T>,
 }
@@ -34,11 +41,13 @@ impl<T: Instance> interrupt::typelevel::Handler<T::Interrupt> for InterruptHandl
    }
 }
+/// RNG driver.
 pub struct Rng<'d, T: Instance> {
    _inner: PeripheralRef<'d, T>,
 }
 impl<'d, T: Instance> Rng<'d, T> {
+    /// Create a new RNG driver.
    pub fn new(
        inner: impl Peripheral<P = T> + 'd,
        _irq: impl interrupt::typelevel::Binding<T::Interrupt, InterruptHandler<T>> + 'd,
@@ -54,6 +63,7 @@ impl<'d, T: Instance> Rng<'d, T> {
        random
    }
+    /// Reset the RNG.
    #[cfg(rng_v1)]
    pub fn reset(&mut self) {
        T::regs().cr().write(|reg| {
@@ -70,6 +80,7 @@ impl<'d, T: Instance> Rng<'d, T> {
        let _ = self.next_u32();
    }
+    /// Reset the RNG.
    #[cfg(not(rng_v1))]
    pub fn reset(&mut self) {
        T::regs().cr().write(|reg| {
@@ -106,7 +117,8 @@ impl<'d, T: Instance> Rng<'d, T> {
        while T::regs().cr().read().condrst() {}
    }
-    pub fn recover_seed_error(&mut self) -> () {
+    /// Try to recover from a seed error.
+    pub fn recover_seed_error(&mut self) {
        self.reset();
        // reset should also clear the SEIS flag
        if T::regs().sr().read().seis() {
@@ -117,6 +129,7 @@ impl<'d, T: Instance> Rng<'d, T> {
        while T::regs().sr().read().secs() {}
    }
+    /// Fill the given slice with random values.
    pub async fn async_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> {
        for chunk in dest.chunks_mut(4) {
            let mut bits = T::regs().sr().read();
@@ -217,7 +230,9 @@ pub(crate) mod sealed {
    }
 }
+/// RNG instance trait.
 pub trait Instance: sealed::Instance + Peripheral<P = Self> + crate::rcc::RccPeripheral + 'static + Send {
+    /// Interrupt for this RNG instance.
    type Interrupt: interrupt::typelevel::Interrupt;
 }
diff --git a/embassy-stm32/src/rtc/datetime.rs b/embassy-stm32/src/rtc/datetime.rs
index f4e86dd87..ef92fa4bb 100644
--- a/embassy-stm32/src/rtc/datetime.rs
+++ b/embassy-stm32/src/rtc/datetime.rs
@@ -104,45 +104,51 @@ pub struct DateTime {
 }
 impl DateTime {
+    /// Get the year (0..=4095)
    pub const fn year(&self) -> u16 {
        self.year
    }
+    /// Get the month (1..=12, 1 is January)
    pub const fn month(&self) -> u8 {
        self.month
    }
+    /// Get the day (1..=31)
    pub const fn day(&self) -> u8 {
        self.day
    }
+    /// Get the day of week
    pub const fn day_of_week(&self) -> DayOfWeek {
        self.day_of_week
    }
+    /// Get the hour (0..=23)
    pub const fn hour(&self) -> u8 {
        self.hour
    }
+    /// Get the minute (0..=59)
    pub const fn minute(&self) -> u8 {
        self.minute
    }
+    /// Get the second (0..=59)
    pub const fn second(&self) -> u8 {
        self.second
    }
+    /// Create a new DateTime with the given information.
    pub fn from(
        year: u16,
        month: u8,
        day: u8,
-        day_of_week: u8,
+        day_of_week: DayOfWeek,
        hour: u8,
        minute: u8,
        second: u8,
    ) -> Result<Self, Error> {
-        let day_of_week = day_of_week_from_u8(day_of_week)?;
        if year > 4095 {
            Err(Error::InvalidYear)
        } else if month < 1 || month > 12 {
diff --git a/embassy-stm32/src/rtc/mod.rs b/embassy-stm32/src/rtc/mod.rs
index b4315f535..1ffb567b3 100644
--- a/embassy-stm32/src/rtc/mod.rs
+++ b/embassy-stm32/src/rtc/mod.rs
@@ -1,4 +1,4 @@
-//! RTC peripheral abstraction
+//! Real Time Clock (RTC)
 mod datetime;
 #[cfg(feature = "low-power")]
@@ -9,9 +9,9 @@ use embassy_sync::blocking_mutex::raw::CriticalSectionRawMutex;
 #[cfg(feature = "low-power")]
 use embassy_sync::blocking_mutex::Mutex;
-use self::datetime::day_of_week_to_u8;
 #[cfg(not(rtc_v2f2))]
 use self::datetime::RtcInstant;
+use self::datetime::{day_of_week_from_u8, day_of_week_to_u8};
 pub use self::datetime::{DateTime, DayOfWeek, Error as DateTimeError};
 use crate::pac::rtc::regs::{Dr, Tr};
 use crate::time::Hertz;
@@ -24,7 +24,7 @@ use crate::time::Hertz;
    ),
    path = "v2.rs"
 )]
-#[cfg_attr(any(rtc_v3, rtc_v3u5), path = "v3.rs")]
+#[cfg_attr(any(rtc_v3, rtc_v3u5, rtc_v3l5), path = "v3.rs")]
 mod _version;
 #[allow(unused_imports)]
 pub use _version::*;
@@ -43,7 +43,7 @@ pub(crate) enum WakeupPrescaler {
    Div16 = 16,
 }
-#[cfg(any(stm32wb, stm32f4, stm32l0, stm32g4))]
+#[cfg(any(stm32wb, stm32f4, stm32l0, stm32g4, stm32l5))]
 impl From<WakeupPrescaler> for crate::pac::rtc::vals::Wucksel {
    fn from(val: WakeupPrescaler) -> Self {
        use crate::pac::rtc::vals::Wucksel;
@@ -57,7 +57,7 @@ impl From<WakeupPrescaler> for crate::pac::rtc::vals::Wucksel {
    }
 }
-#[cfg(any(stm32wb, stm32f4, stm32l0, stm32g4))]
+#[cfg(any(stm32wb, stm32f4, stm32l0, stm32g4, stm32l5))]
 impl From<crate::pac::rtc::vals::Wucksel> for WakeupPrescaler {
    fn from(val: crate::pac::rtc::vals::Wucksel) -> Self {
        use crate::pac::rtc::vals::Wucksel;
@@ -102,6 +102,7 @@ pub enum RtcError {
    NotRunning,
 }
+/// Provides immutable access to the current time of the RTC.
 pub struct RtcTimeProvider {
    _private: (),
 }
@@ -127,10 +128,10 @@ impl RtcTimeProvider {
            let minute = bcd2_to_byte((tr.mnt(), tr.mnu()));
            let hour = bcd2_to_byte((tr.ht(), tr.hu()));
-            let weekday = dr.wdu();
+            let weekday = day_of_week_from_u8(dr.wdu()).map_err(RtcError::InvalidDateTime)?;
            let day = bcd2_to_byte((dr.dt(), dr.du()));
            let month = bcd2_to_byte((dr.mt() as u8, dr.mu()));
-            let year = bcd2_to_byte((dr.yt(), dr.yu())) as u16 + 1970_u16;
+            let year = bcd2_to_byte((dr.yt(), dr.yu())) as u16 + 2000_u16;
            DateTime::from(year, month, day, weekday, hour, minute, second).map_err(RtcError::InvalidDateTime)
        })
@@ -163,7 +164,7 @@ impl RtcTimeProvider {
    }
 }
-/// RTC Abstraction
+/// RTC driver.
 pub struct Rtc {
    #[cfg(feature = "low-power")]
    stop_time: Mutex<CriticalSectionRawMutex, Cell<Option<RtcInstant>>>,
@@ -171,6 +172,7 @@ pub struct Rtc {
    _private: (),
 }
+/// RTC configuration.
 #[non_exhaustive]
 #[derive(Copy, Clone, PartialEq)]
 pub struct RtcConfig {
@@ -188,6 +190,7 @@ impl Default for RtcConfig {
    }
 }
+/// Calibration cycle period.
 #[derive(Copy, Clone, Debug, PartialEq)]
 #[repr(u8)]
 pub enum RtcCalibrationCyclePeriod {
@@ -206,6 +209,7 @@ impl Default for RtcCalibrationCyclePeriod {
 }
 impl Rtc {
+    /// Create a new RTC instance.
    pub fn new(_rtc: impl Peripheral<P = RTC>, rtc_config: RtcConfig) -> Self {
        #[cfg(not(any(stm32l0, stm32f3, stm32l1, stm32f0, stm32f2)))]
        <RTC as crate::rcc::sealed::RccPeripheral>::enable_and_reset();
@@ -258,7 +262,7 @@ impl Rtc {
            let (dt, du) = byte_to_bcd2(t.day() as u8);
            let (mt, mu) = byte_to_bcd2(t.month() as u8);
            let yr = t.year() as u16;
-            let yr_offset = (yr - 1970_u16) as u8;
+            let yr_offset = (yr - 2000_u16) as u8;
            let (yt, yu) = byte_to_bcd2(yr_offset);
            use crate::pac::rtc::vals::Ampm;
@@ -315,6 +319,7 @@ impl Rtc {
        })
    }
+    /// Number of backup registers of this instance.
    pub const BACKUP_REGISTER_COUNT: usize = RTC::BACKUP_REGISTER_COUNT;
    /// Read content of the backup register.
@@ -343,7 +348,7 @@ impl Rtc {
    ) {
        use embassy_time::{Duration, TICK_HZ};
-        #[cfg(any(rtc_v3, rtc_v3u5))]
+        #[cfg(any(rtc_v3, rtc_v3u5, rtc_v3l5))]
        use crate::pac::rtc::vals::Calrf;
        // Panic if the rcc mod knows we're not using low-power rtc
@@ -370,7 +375,7 @@ impl Rtc {
                while !regs.isr().read().wutwf() {}
            }
-            #[cfg(any(rtc_v3, rtc_v3u5))]
+            #[cfg(any(rtc_v3, rtc_v3u5, rtc_v3l5))]
            {
                regs.scr().write(|w| w.set_cwutf(Calrf::CLEAR));
                while !regs.icsr().read().wutwf() {}
@@ -399,7 +404,7 @@ impl Rtc {
    /// was called, otherwise none
    pub(crate) fn stop_wakeup_alarm(&self, cs: critical_section::CriticalSection) -> Option<embassy_time::Duration> {
        use crate::interrupt::typelevel::Interrupt;
-        #[cfg(any(rtc_v3, rtc_v3u5))]
+        #[cfg(any(rtc_v3, rtc_v3u5, rtc_v3l5))]
        use crate::pac::rtc::vals::Calrf;
        let instant = self.instant().unwrap();
@@ -415,13 +420,19 @@ impl Rtc {
                ))]
                regs.isr().modify(|w| w.set_wutf(false));
-                #[cfg(any(rtc_v3, rtc_v3u5))]
+                #[cfg(any(rtc_v3, rtc_v3u5, rtc_v3l5))]
                regs.scr().write(|w| w.set_cwutf(Calrf::CLEAR));
+                #[cfg(not(stm32l5))]
                crate::pac::EXTI
                    .pr(0)
                    .modify(|w| w.set_line(RTC::EXTI_WAKEUP_LINE, true));
+                #[cfg(stm32l5)]
+                crate::pac::EXTI
+                    .fpr(0)
+                    .modify(|w| w.set_line(RTC::EXTI_WAKEUP_LINE, true));
                <RTC as crate::rtc::sealed::Instance>::WakeupInterrupt::unpend();
            });
        }
diff --git a/embassy-stm32/src/rtc/v2.rs b/embassy-stm32/src/rtc/v2.rs
index 91f08fae4..1eda097a7 100644
--- a/embassy-stm32/src/rtc/v2.rs
+++ b/embassy-stm32/src/rtc/v2.rs
@@ -1,4 +1,4 @@
-use stm32_metapac::rtc::vals::{Init, Osel, Pol};
+use stm32_metapac::rtc::vals::{Osel, Pol};
 use super::sealed;
 use crate::pac::rtc::Rtc;
@@ -49,7 +49,7 @@ impl super::Rtc {
            clock_drift = RTC_CALR_MAX_PPM;
        }
-        clock_drift = clock_drift / RTC_CALR_RESOLUTION_PPM;
+        clock_drift /= RTC_CALR_RESOLUTION_PPM;
        self.write(false, |rtc| {
            rtc.calr().write(|w| {
@@ -107,7 +107,7 @@ impl super::Rtc {
        // true if initf bit indicates RTC peripheral is in init mode
        if init_mode && !r.isr().read().initf() {
            // to update calendar date/time, time format, and prescaler configuration, RTC must be in init mode
-            r.isr().modify(|w| w.set_init(Init::INITMODE));
+            r.isr().modify(|w| w.set_init(true));
            // wait till init state entered
            // ~2 RTCCLK cycles
            while !r.isr().read().initf() {}
@@ -116,7 +116,7 @@ impl super::Rtc {
        let result = f(&r);
        if init_mode {
-            r.isr().modify(|w| w.set_init(Init::FREERUNNINGMODE)); // Exits init mode
+            r.isr().modify(|w| w.set_init(false)); // Exits init mode
        }
        // Re-enable write protection.
diff --git a/embassy-stm32/src/rtc/v3.rs b/embassy-stm32/src/rtc/v3.rs
index d2d0d9309..114141b64 100644
--- a/embassy-stm32/src/rtc/v3.rs
+++ b/embassy-stm32/src/rtc/v3.rs
@@ -1,4 +1,4 @@
-use stm32_metapac::rtc::vals::{Calp, Calw16, Calw8, Fmt, Init, Key, Osel, Pol, TampalrmPu, TampalrmType};
+use stm32_metapac::rtc::vals::{Calp, Calw16, Calw8, Fmt, Key, Osel, Pol, TampalrmType};
 use super::{sealed, RtcCalibrationCyclePeriod};
 use crate::pac::rtc::Rtc;
@@ -26,7 +26,7 @@ impl super::Rtc {
            rtc.cr().modify(|w| {
                w.set_out2en(false);
                w.set_tampalrm_type(TampalrmType::PUSHPULL);
-                w.set_tampalrm_pu(TampalrmPu::NOPULLUP);
+                w.set_tampalrm_pu(false);
            });
        });
    }
@@ -106,7 +106,7 @@ impl super::Rtc {
        r.wpr().write(|w| w.set_key(Key::DEACTIVATE2));
        if init_mode && !r.icsr().read().initf() {
-            r.icsr().modify(|w| w.set_init(Init::INITMODE));
+            r.icsr().modify(|w| w.set_init(true));
            // wait till init state entered
            // ~2 RTCCLK cycles
            while !r.icsr().read().initf() {}
@@ -115,7 +115,7 @@ impl super::Rtc {
        let result = f(&r);
        if init_mode {
-            r.icsr().modify(|w| w.set_init(Init::FREERUNNINGMODE)); // Exits init mode
+            r.icsr().modify(|w| w.set_init(false)); // Exits init mode
        }
        // Re-enable write protection.
@@ -135,6 +135,12 @@ impl sealed::Instance for crate::peripherals::RTC {
    #[cfg(all(feature = "low-power", stm32g4))]
    type WakeupInterrupt = crate::interrupt::typelevel::RTC_WKUP;
+    #[cfg(all(feature = "low-power", stm32l5))]
+    const EXTI_WAKEUP_LINE: usize = 17;
+    #[cfg(all(feature = "low-power", stm32l5))]
+    type WakeupInterrupt = crate::interrupt::typelevel::RTC;
    fn read_backup_register(_rtc: &Rtc, register: usize) -> Option<u32> {
        #[allow(clippy::if_same_then_else)]
        if register < Self::BACKUP_REGISTER_COUNT {
diff --git a/embassy-stm32/src/sai/mod.rs b/embassy-stm32/src/sai/mod.rs
index a16d38af1..ef8802184 100644
--- a/embassy-stm32/src/sai/mod.rs
+++ b/embassy-stm32/src/sai/mod.rs
@@ -1,8 +1,11 @@
+//! Serial Audio Interface (SAI)
 #![macro_use]
-use embassy_embedded_hal::SetConfig;
+use core::marker::PhantomData;
 use embassy_hal_internal::{into_ref, PeripheralRef};
+use self::sealed::WhichSubBlock;
 pub use crate::dma::word;
 use crate::dma::{ringbuffer, Channel, ReadableRingBuffer, Request, TransferOptions, WritableRingBuffer};
 use crate::gpio::sealed::{AFType, Pin as _};
@@ -11,48 +14,32 @@ use crate::pac::sai::{vals, Sai as Regs};
 use crate::rcc::RccPeripheral;
 use crate::{peripherals, Peripheral};
+/// SAI error
 #[derive(Debug, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Error {
+    /// `write` called on a SAI in receive mode.
    NotATransmitter,
+    /// `read` called on a SAI in transmit mode.
    NotAReceiver,
-    OverrunError,
+    /// Overrun
+    Overrun,
 }
 impl From<ringbuffer::OverrunError> for Error {
    fn from(_: ringbuffer::OverrunError) -> Self {
-        Self::OverrunError
+        Self::Overrun
    }
 }
+/// Master/slave mode.
 #[derive(Copy, Clone)]
-pub enum SyncBlock {
+#[allow(missing_docs)]
-    None,
-    Sai1BlockA,
-    Sai1BlockB,
-    Sai2BlockA,
-    Sai2BlockB,
-}
-#[derive(Copy, Clone)]
-pub enum SyncIn {
-    None,
-    ChannelZero,
-    ChannelOne,
-}
-#[derive(Copy, Clone)]
 pub enum Mode {
    Master,
    Slave,
 }
-#[derive(Copy, Clone)]
-pub enum TxRx {
-    Transmitter,
-    Receiver,
-}
 impl Mode {
    #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
    const fn mode(&self, tx_rx: TxRx) -> vals::Mode {
@@ -69,7 +56,17 @@ impl Mode {
    }
 }
+/// Direction: transmit or receive
 #[derive(Copy, Clone)]
+#[allow(missing_docs)]
+pub enum TxRx {
+    Transmitter,
+    Receiver,
+}
+/// Data slot size.
+#[derive(Copy, Clone)]
+#[allow(missing_docs)]
 pub enum SlotSize {
    DataSize,
    /// 16 bit data length on 16 bit wide channel
@@ -80,7 +77,7 @@ pub enum SlotSize {
 impl SlotSize {
    #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn slotsz(&self) -> vals::Slotsz {
+    const fn slotsz(&self) -> vals::Slotsz {
        match self {
            SlotSize::DataSize => vals::Slotsz::DATASIZE,
            SlotSize::Channel16 => vals::Slotsz::BIT16,
@@ -89,7 +86,9 @@ impl SlotSize {
    }
 }
+/// Data size.
 #[derive(Copy, Clone)]
+#[allow(missing_docs)]
 pub enum DataSize {
    Data8,
    Data10,
@@ -101,7 +100,7 @@ pub enum DataSize {
 impl DataSize {
    #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn ds(&self) -> vals::Ds {
+    const fn ds(&self) -> vals::Ds {
        match self {
            DataSize::Data8 => vals::Ds::BIT8,
            DataSize::Data10 => vals::Ds::BIT10,
@@ -113,7 +112,9 @@ impl DataSize {
    }
 }
+/// FIFO threshold level.
 #[derive(Copy, Clone)]
+#[allow(missing_docs)]
 pub enum FifoThreshold {
    Empty,
    Quarter,
@@ -124,7 +125,7 @@ pub enum FifoThreshold {
 impl FifoThreshold {
    #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn fth(&self) -> vals::Fth {
+    const fn fth(&self) -> vals::Fth {
        match self {
            FifoThreshold::Empty => vals::Fth::EMPTY,
            FifoThreshold::Quarter => vals::Fth::QUARTER1,
@@ -135,38 +136,9 @@ impl FifoThreshold {
    }
 }
+/// Output value on mute.
 #[derive(Copy, Clone)]
-pub enum FifoLevel {
+#[allow(missing_docs)]
-    Empty,
-    FirstQuarter,
-    SecondQuarter,
-    ThirdQuarter,
-    FourthQuarter,
-    Full,
-}
-#[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-impl From<vals::Flvl> for FifoLevel {
-    fn from(flvl: vals::Flvl) -> Self {
-        match flvl {
-            vals::Flvl::EMPTY => FifoLevel::Empty,
-            vals::Flvl::QUARTER1 => FifoLevel::FirstQuarter,
-            vals::Flvl::QUARTER2 => FifoLevel::SecondQuarter,
-            vals::Flvl::QUARTER3 => FifoLevel::ThirdQuarter,
-            vals::Flvl::QUARTER4 => FifoLevel::FourthQuarter,
-            vals::Flvl::FULL => FifoLevel::Full,
-            _ => FifoLevel::Empty,
-        }
-    }
-}
-#[derive(Copy, Clone)]
-pub enum MuteDetection {
-    NoMute,
-    Mute,
-}
-#[derive(Copy, Clone)]
 pub enum MuteValue {
    Zero,
    LastValue,
@@ -174,7 +146,7 @@ pub enum MuteValue {
 impl MuteValue {
    #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn muteval(&self) -> vals::Muteval {
+    const fn muteval(&self) -> vals::Muteval {
        match self {
            MuteValue::Zero => vals::Muteval::SENDZERO,
            MuteValue::LastValue => vals::Muteval::SENDLAST,
@@ -182,13 +154,9 @@ impl MuteValue {
    }
 }
+/// Protocol variant to use.
 #[derive(Copy, Clone)]
-pub enum OverUnderStatus {
+#[allow(missing_docs)]
-    NoError,
-    OverUnderRunDetected,
-}
-#[derive(Copy, Clone)]
 pub enum Protocol {
    Free,
    Spdif,
@@ -197,7 +165,7 @@ pub enum Protocol {
 impl Protocol {
    #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn prtcfg(&self) -> vals::Prtcfg {
+    const fn prtcfg(&self) -> vals::Prtcfg {
        match self {
            Protocol::Free => vals::Prtcfg::FREE,
            Protocol::Spdif => vals::Prtcfg::SPDIF,
@@ -206,7 +174,9 @@ impl Protocol {
    }
 }
+/// Sync input between SAI units/blocks.
 #[derive(Copy, Clone, PartialEq)]
+#[allow(missing_docs)]
 pub enum SyncInput {
    /// Not synced to any other SAI unit.
    None,
@@ -218,7 +188,7 @@ pub enum SyncInput {
 }
 impl SyncInput {
-    pub const fn syncen(&self) -> vals::Syncen {
+    const fn syncen(&self) -> vals::Syncen {
        match self {
            SyncInput::None => vals::Syncen::ASYNCHRONOUS,
            SyncInput::Internal => vals::Syncen::INTERNAL,
@@ -228,8 +198,10 @@ impl SyncInput {
    }
 }
+/// SAI instance to sync from.
 #[cfg(sai_v4)]
 #[derive(Copy, Clone, PartialEq)]
+#[allow(missing_docs)]
 pub enum SyncInputInstance {
    #[cfg(peri_sai1)]
    Sai1 = 0,
@@ -241,7 +213,9 @@ pub enum SyncInputInstance {
    Sai4 = 3,
 }
+/// Channels (stereo or mono).
 #[derive(Copy, Clone, PartialEq)]
+#[allow(missing_docs)]
 pub enum StereoMono {
    Stereo,
    Mono,
@@ -249,7 +223,7 @@ pub enum StereoMono {
 impl StereoMono {
    #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn mono(&self) -> vals::Mono {
+    const fn mono(&self) -> vals::Mono {
        match self {
            StereoMono::Stereo => vals::Mono::STEREO,
            StereoMono::Mono => vals::Mono::MONO,
@@ -257,15 +231,18 @@ impl StereoMono {
    }
 }
+/// Bit order
 #[derive(Copy, Clone)]
 pub enum BitOrder {
+    /// Least significant bit first.
    LsbFirst,
+    /// Most significant bit first.
    MsbFirst,
 }
 impl BitOrder {
    #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn lsbfirst(&self) -> vals::Lsbfirst {
+    const fn lsbfirst(&self) -> vals::Lsbfirst {
        match self {
            BitOrder::LsbFirst => vals::Lsbfirst::LSBFIRST,
            BitOrder::MsbFirst => vals::Lsbfirst::MSBFIRST,
@@ -273,6 +250,7 @@ impl BitOrder {
    }
 }
+/// Frame sync offset.
 #[derive(Copy, Clone)]
 pub enum FrameSyncOffset {
    /// This is used in modes other than standard I2S phillips mode
@@ -283,7 +261,7 @@ pub enum FrameSyncOffset {
 impl FrameSyncOffset {
    #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn fsoff(&self) -> vals::Fsoff {
+    const fn fsoff(&self) -> vals::Fsoff {
        match self {
            FrameSyncOffset::OnFirstBit => vals::Fsoff::ONFIRST,
            FrameSyncOffset::BeforeFirstBit => vals::Fsoff::BEFOREFIRST,
@@ -291,15 +269,18 @@ impl FrameSyncOffset {
    }
 }
+/// Frame sync polarity
 #[derive(Copy, Clone)]
 pub enum FrameSyncPolarity {
+    /// Sync signal is active low.
    ActiveLow,
+    /// Sync signal is active high
    ActiveHigh,
 }
 impl FrameSyncPolarity {
    #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn fspol(&self) -> vals::Fspol {
+    const fn fspol(&self) -> vals::Fspol {
        match self {
            FrameSyncPolarity::ActiveLow => vals::Fspol::FALLINGEDGE,
            FrameSyncPolarity::ActiveHigh => vals::Fspol::RISINGEDGE,
@@ -307,7 +288,9 @@ impl FrameSyncPolarity {
    }
 }
+/// Sync definition.
 #[derive(Copy, Clone)]
+#[allow(missing_docs)]
 pub enum FrameSyncDefinition {
    StartOfFrame,
    ChannelIdentification,
@@ -315,7 +298,7 @@ pub enum FrameSyncDefinition {
 impl FrameSyncDefinition {
    #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn fsdef(&self) -> bool {
+    const fn fsdef(&self) -> bool {
        match self {
            FrameSyncDefinition::StartOfFrame => false,
            FrameSyncDefinition::ChannelIdentification => true,
@@ -323,7 +306,9 @@ impl FrameSyncDefinition {
    }
 }
+/// Clock strobe.
 #[derive(Copy, Clone)]
+#[allow(missing_docs)]
 pub enum ClockStrobe {
    Falling,
    Rising,
@@ -331,7 +316,7 @@ pub enum ClockStrobe {
 impl ClockStrobe {
    #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn ckstr(&self) -> vals::Ckstr {
+    const fn ckstr(&self) -> vals::Ckstr {
        match self {
            ClockStrobe::Falling => vals::Ckstr::FALLINGEDGE,
            ClockStrobe::Rising => vals::Ckstr::RISINGEDGE,
@@ -339,7 +324,9 @@ impl ClockStrobe {
    }
 }
+/// Complements format for negative samples.
 #[derive(Copy, Clone)]
+#[allow(missing_docs)]
 pub enum ComplementFormat {
    OnesComplement,
    TwosComplement,
@@ -347,7 +334,7 @@ pub enum ComplementFormat {
 impl ComplementFormat {
    #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn cpl(&self) -> vals::Cpl {
+    const fn cpl(&self) -> vals::Cpl {
        match self {
            ComplementFormat::OnesComplement => vals::Cpl::ONESCOMPLEMENT,
            ComplementFormat::TwosComplement => vals::Cpl::TWOSCOMPLEMENT,
@@ -355,7 +342,9 @@ impl ComplementFormat {
    }
 }
+/// Companding setting.
 #[derive(Copy, Clone)]
+#[allow(missing_docs)]
 pub enum Companding {
    None,
    MuLaw,
@@ -364,7 +353,7 @@ pub enum Companding {
 impl Companding {
    #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn comp(&self) -> vals::Comp {
+    const fn comp(&self) -> vals::Comp {
        match self {
            Companding::None => vals::Comp::NOCOMPANDING,
            Companding::MuLaw => vals::Comp::MULAW,
@@ -373,7 +362,9 @@ impl Companding {
    }
 }
+/// Output drive
 #[derive(Copy, Clone)]
+#[allow(missing_docs)]
 pub enum OutputDrive {
    OnStart,
    Immediately,
@@ -381,7 +372,7 @@ pub enum OutputDrive {
 impl OutputDrive {
    #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn outdriv(&self) -> vals::Outdriv {
+    const fn outdriv(&self) -> vals::Outdriv {
        match self {
            OutputDrive::OnStart => vals::Outdriv::ONSTART,
            OutputDrive::Immediately => vals::Outdriv::IMMEDIATELY,
@@ -389,7 +380,9 @@ impl OutputDrive {
    }
 }
+/// Master clock divider.
 #[derive(Copy, Clone, PartialEq)]
+#[allow(missing_docs)]
 pub enum MasterClockDivider {
    MasterClockDisabled,
    Div1,
@@ -412,7 +405,7 @@ pub enum MasterClockDivider {
 impl MasterClockDivider {
    #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn mckdiv(&self) -> u8 {
+    const fn mckdiv(&self) -> u8 {
        match self {
            MasterClockDivider::MasterClockDisabled => 0,
            MasterClockDivider::Div1 => 0,
@@ -436,6 +429,7 @@ impl MasterClockDivider {
 }
 /// [`SAI`] configuration.
+#[allow(missing_docs)]
 #[non_exhaustive]
 #[derive(Copy, Clone)]
 pub struct Config {
@@ -459,7 +453,7 @@ pub struct Config {
    pub clock_strobe: ClockStrobe,
    pub output_drive: OutputDrive,
    pub master_clock_divider: MasterClockDivider,
-    pub is_high_impedenane_on_inactive_slot: bool,
+    pub is_high_impedance_on_inactive_slot: bool,
    pub fifo_threshold: FifoThreshold,
    pub companding: Companding,
    pub complement_format: ComplementFormat,
@@ -490,7 +484,7 @@ impl Default for Config {
            master_clock_divider: MasterClockDivider::MasterClockDisabled,
            clock_strobe: ClockStrobe::Rising,
            output_drive: OutputDrive::Immediately,
-            is_high_impedenane_on_inactive_slot: false,
+            is_high_impedance_on_inactive_slot: false,
            fifo_threshold: FifoThreshold::ThreeQuarters,
            companding: Companding::None,
            complement_format: ComplementFormat::TwosComplement,
@@ -501,23 +495,10 @@ impl Default for Config {
 }
 impl Config {
-    pub fn new_i2s() -> Self {
+    /// Create a new config with all default values.
+    pub fn new() -> Self {
        return Default::default();
    }
-    pub fn new_msb_first() -> Self {
-        Self {
-            bit_order: BitOrder::MsbFirst,
-            frame_sync_offset: FrameSyncOffset::OnFirstBit,
-            ..Default::default()
-        }
-    }
-}
-#[derive(Copy, Clone)]
-enum WhichSubBlock {
-    A = 0,
-    B = 1,
 }
 enum RingBuffer<'d, C: Channel, W: word::Word> {
@@ -531,28 +512,6 @@ fn dr<W: word::Word>(w: crate::pac::sai::Sai, sub_block: WhichSubBlock) -> *mut
    ch.dr().as_ptr() as _
 }
-pub struct SubBlock<'d, T: Instance, C: Channel, W: word::Word> {
-    _peri: PeripheralRef<'d, T>,
-    sd: Option<PeripheralRef<'d, AnyPin>>,
-    fs: Option<PeripheralRef<'d, AnyPin>>,
-    sck: Option<PeripheralRef<'d, AnyPin>>,
-    mclk: Option<PeripheralRef<'d, AnyPin>>,
-    ring_buffer: RingBuffer<'d, C, W>,
-    sub_block: WhichSubBlock,
-}
-pub struct SubBlockA {}
-pub struct SubBlockB {}
-pub struct SubBlockAPeripheral<'d, T>(PeripheralRef<'d, T>);
-pub struct SubBlockBPeripheral<'d, T>(PeripheralRef<'d, T>);
-pub struct Sai<'d, T: Instance> {
-    _peri: PeripheralRef<'d, T>,
-    sub_block_a_peri: Option<SubBlockAPeripheral<'d, T>>,
-    sub_block_b_peri: Option<SubBlockBPeripheral<'d, T>>,
-}
 // return the type for (sd, sck)
 fn get_af_types(mode: Mode, tx_rx: TxRx) -> (AFType, AFType) {
    (
@@ -583,42 +542,14 @@ fn get_ring_buffer<'d, T: Instance, C: Channel, W: word::Word>(
    };
    match tx_rx {
        TxRx::Transmitter => RingBuffer::Writable(unsafe {
-            WritableRingBuffer::new_write(dma, request, dr(T::REGS, sub_block), dma_buf, opts)
+            WritableRingBuffer::new(dma, request, dr(T::REGS, sub_block), dma_buf, opts)
        }),
        TxRx::Receiver => RingBuffer::Readable(unsafe {
-            ReadableRingBuffer::new_read(dma, request, dr(T::REGS, sub_block), dma_buf, opts)
+            ReadableRingBuffer::new(dma, request, dr(T::REGS, sub_block), dma_buf, opts)
        }),
    }
 }
-impl<'d, T: Instance> Sai<'d, T> {
-    pub fn new(peri: impl Peripheral<P = T> + 'd) -> Self {
-        T::enable_and_reset();
-        Self {
-            _peri: unsafe { peri.clone_unchecked().into_ref() },
-            sub_block_a_peri: Some(SubBlockAPeripheral(unsafe { peri.clone_unchecked().into_ref() })),
-            sub_block_b_peri: Some(SubBlockBPeripheral(peri.into_ref())),
-        }
-    }
-    pub fn take_sub_block_a(self: &mut Self) -> Option<SubBlockAPeripheral<'d, T>> {
-        if self.sub_block_a_peri.is_some() {
-            self.sub_block_a_peri.take()
-        } else {
-            None
-        }
-    }
-    pub fn take_sub_block_b(self: &mut Self) -> Option<SubBlockBPeripheral<'d, T>> {
-        if self.sub_block_b_peri.is_some() {
-            self.sub_block_b_peri.take()
-        } else {
-            None
-        }
-    }
-}
 fn update_synchronous_config(config: &mut Config) {
    config.mode = Mode::Slave;
    config.sync_output = false;
@@ -636,122 +567,58 @@ fn update_synchronous_config(config: &mut Config) {
    }
 }
-impl SubBlockA {
+/// SAI subblock instance.
-    pub fn new_asynchronous_with_mclk<'d, T: Instance, C: Channel, W: word::Word>(
+pub struct SubBlock<'d, T, S: SubBlockInstance> {
-        peri: SubBlockAPeripheral<'d, T>,
+    peri: PeripheralRef<'d, T>,
-        sck: impl Peripheral<P = impl SckAPin<T>> + 'd,
+    _phantom: PhantomData<S>,
-        sd: impl Peripheral<P = impl SdAPin<T>> + 'd,
+}
-        fs: impl Peripheral<P = impl FsAPin<T>> + 'd,
-        mclk: impl Peripheral<P = impl MclkAPin<T>> + 'd,
-        dma: impl Peripheral<P = C> + 'd,
-        dma_buf: &'d mut [W],
-        mut config: Config,
-    ) -> SubBlock<'d, T, C, W>
-    where
-        C: Channel + DmaA<T>,
-    {
-        into_ref!(mclk);
-        let (_sd_af_type, ck_af_type) = get_af_types(config.mode, config.tx_rx);
-        mclk.set_as_af(mclk.af_num(), ck_af_type);
-        mclk.set_speed(crate::gpio::Speed::VeryHigh);
-        if config.master_clock_divider == MasterClockDivider::MasterClockDisabled {
-            config.master_clock_divider = MasterClockDivider::Div1;
-        }
-        Self::new_asynchronous(peri, sck, sd, fs, dma, dma_buf, config)
-    }
-    pub fn new_asynchronous<'d, T: Instance, C: Channel, W: word::Word>(
-        peri: SubBlockAPeripheral<'d, T>,
-        sck: impl Peripheral<P = impl SckAPin<T>> + 'd,
-        sd: impl Peripheral<P = impl SdAPin<T>> + 'd,
-        fs: impl Peripheral<P = impl FsAPin<T>> + 'd,
-        dma: impl Peripheral<P = C> + 'd,
-        dma_buf: &'d mut [W],
-        config: Config,
-    ) -> SubBlock<'d, T, C, W>
-    where
-        C: Channel + DmaA<T>,
-    {
-        let peri = peri.0;
-        into_ref!(peri, dma, sck, sd, fs);
-        let (sd_af_type, ck_af_type) = get_af_types(config.mode, config.tx_rx);
-        sd.set_as_af(sd.af_num(), sd_af_type);
-        sd.set_speed(crate::gpio::Speed::VeryHigh);
-        sck.set_as_af(sck.af_num(), ck_af_type);
-        sck.set_speed(crate::gpio::Speed::VeryHigh);
-        fs.set_as_af(fs.af_num(), ck_af_type);
-        fs.set_speed(crate::gpio::Speed::VeryHigh);
-        let sub_block = WhichSubBlock::A;
+/// Split the main SAIx peripheral into the two subblocks.
-        let request = dma.request();
+///
+/// You can then create a [`Sai`] driver for each each half.
+pub fn split_subblocks<'d, T: Instance>(peri: impl Peripheral<P = T> + 'd) -> (SubBlock<'d, T, A>, SubBlock<'d, T, B>) {
+    into_ref!(peri);
+    T::enable_and_reset();
-        SubBlock::new_inner(
+    (
+        SubBlock {
+            peri: unsafe { peri.clone_unchecked() },
+            _phantom: PhantomData,
+        },
+        SubBlock {
            peri,
-            sub_block,
+            _phantom: PhantomData,
-            Some(sck.map_into()),
+        },
-            None,
+    )
-            Some(sd.map_into()),
+}
-            Some(fs.map_into()),
-            get_ring_buffer::<T, C, W>(dma, dma_buf, request, sub_block, config.tx_rx),
-            config,
-        )
-    }
-    pub fn new_synchronous<'d, T: Instance, C: Channel, W: word::Word>(
-        peri: SubBlockAPeripheral<'d, T>,
-        sd: impl Peripheral<P = impl SdAPin<T>> + 'd,
-        dma: impl Peripheral<P = C> + 'd,
-        dma_buf: &'d mut [W],
-        mut config: Config,
-    ) -> SubBlock<'d, T, C, W>
-    where
-        C: Channel + DmaA<T>,
-    {
-        update_synchronous_config(&mut config);
-        let peri = peri.0;
-        into_ref!(dma, peri, sd);
-        let (sd_af_type, _ck_af_type) = get_af_types(config.mode, config.tx_rx);
-        sd.set_as_af(sd.af_num(), sd_af_type);
-        sd.set_speed(crate::gpio::Speed::VeryHigh);
-        let sub_block = WhichSubBlock::A;
-        let request = dma.request();
-        SubBlock::new_inner(
+/// SAI sub-block driver.
-            peri,
+pub struct Sai<'d, T: Instance, C: Channel, W: word::Word> {
-            sub_block,
+    _peri: PeripheralRef<'d, T>,
-            None,
+    sd: Option<PeripheralRef<'d, AnyPin>>,
-            None,
+    fs: Option<PeripheralRef<'d, AnyPin>>,
-            Some(sd.map_into()),
+    sck: Option<PeripheralRef<'d, AnyPin>>,
-            None,
+    mclk: Option<PeripheralRef<'d, AnyPin>>,
-            get_ring_buffer::<T, C, W>(dma, dma_buf, request, sub_block, config.tx_rx),
+    ring_buffer: RingBuffer<'d, C, W>,
-            config,
+    sub_block: WhichSubBlock,
-        )
-    }
 }
-impl SubBlockB {
+impl<'d, T: Instance, C: Channel, W: word::Word> Sai<'d, T, C, W> {
-    pub fn new_asynchronous_with_mclk<'d, T: Instance, C: Channel, W: word::Word>(
+    /// Create a new SAI driver in asynchronous mode with MCLK.
-        peri: SubBlockBPeripheral<'d, T>,
+    ///
-        sck: impl Peripheral<P = impl SckBPin<T>> + 'd,
+    /// You can obtain the [`SubBlock`] with [`split_subblocks`].
-        sd: impl Peripheral<P = impl SdBPin<T>> + 'd,
+    pub fn new_asynchronous_with_mclk<S: SubBlockInstance>(
-        fs: impl Peripheral<P = impl FsBPin<T>> + 'd,
+        peri: SubBlock<'d, T, S>,
-        mclk: impl Peripheral<P = impl MclkBPin<T>> + 'd,
+        sck: impl Peripheral<P = impl SckPin<T, S>> + 'd,
+        sd: impl Peripheral<P = impl SdPin<T, S>> + 'd,
+        fs: impl Peripheral<P = impl FsPin<T, S>> + 'd,
+        mclk: impl Peripheral<P = impl MclkPin<T, S>> + 'd,
        dma: impl Peripheral<P = C> + 'd,
        dma_buf: &'d mut [W],
        mut config: Config,
-    ) -> SubBlock<'d, T, C, W>
+    ) -> Self
    where
-        C: Channel + DmaB<T>,
+        C: Channel + Dma<T, S>,
    {
        into_ref!(mclk);
@@ -767,23 +634,25 @@ impl SubBlockB {
        Self::new_asynchronous(peri, sck, sd, fs, dma, dma_buf, config)
    }
-    pub fn new_asynchronous<'d, T: Instance, C: Channel, W: word::Word>(
+    /// Create a new SAI driver in asynchronous mode without MCLK.
-        peri: SubBlockBPeripheral<'d, T>,
+    ///
-        sck: impl Peripheral<P = impl SckBPin<T>> + 'd,
+    /// You can obtain the [`SubBlock`] with [`split_subblocks`].
-        sd: impl Peripheral<P = impl SdBPin<T>> + 'd,
+    pub fn new_asynchronous<S: SubBlockInstance>(
-        fs: impl Peripheral<P = impl FsBPin<T>> + 'd,
+        peri: SubBlock<'d, T, S>,
+        sck: impl Peripheral<P = impl SckPin<T, S>> + 'd,
+        sd: impl Peripheral<P = impl SdPin<T, S>> + 'd,
+        fs: impl Peripheral<P = impl FsPin<T, S>> + 'd,
        dma: impl Peripheral<P = C> + 'd,
        dma_buf: &'d mut [W],
        config: Config,
-    ) -> SubBlock<'d, T, C, W>
+    ) -> Self
    where
-        C: Channel + DmaB<T>,
+        C: Channel + Dma<T, S>,
    {
-        let peri = peri.0;
+        let peri = peri.peri;
-        into_ref!(dma, peri, sck, sd, fs);
+        into_ref!(peri, dma, sck, sd, fs);
        let (sd_af_type, ck_af_type) = get_af_types(config.mode, config.tx_rx);
        sd.set_as_af(sd.af_num(), sd_af_type);
        sd.set_speed(crate::gpio::Speed::VeryHigh);
@@ -792,10 +661,10 @@ impl SubBlockB {
        fs.set_as_af(fs.af_num(), ck_af_type);
        fs.set_speed(crate::gpio::Speed::VeryHigh);
-        let sub_block = WhichSubBlock::B;
+        let sub_block = S::WHICH;
        let request = dma.request();
-        SubBlock::new_inner(
+        Self::new_inner(
            peri,
            sub_block,
            Some(sck.map_into()),
@@ -807,18 +676,22 @@ impl SubBlockB {
        )
    }
-    pub fn new_synchronous<'d, T: Instance, C: Channel, W: word::Word>(
+    /// Create a new SAI driver in synchronous mode.
-        peri: SubBlockBPeripheral<'d, T>,
+    ///
-        sd: impl Peripheral<P = impl SdBPin<T>> + 'd,
+    /// You can obtain the [`SubBlock`] with [`split_subblocks`].
+    pub fn new_synchronous<S: SubBlockInstance>(
+        peri: SubBlock<'d, T, S>,
+        sd: impl Peripheral<P = impl SdPin<T, S>> + 'd,
        dma: impl Peripheral<P = C> + 'd,
        dma_buf: &'d mut [W],
        mut config: Config,
-    ) -> SubBlock<'d, T, C, W>
+    ) -> Self
    where
-        C: Channel + DmaB<T>,
+        C: Channel + Dma<T, S>,
    {
        update_synchronous_config(&mut config);
-        let peri = peri.0;
+        let peri = peri.peri;
        into_ref!(dma, peri, sd);
        let (sd_af_type, _ck_af_type) = get_af_types(config.mode, config.tx_rx);
@@ -826,10 +699,10 @@ impl SubBlockB {
        sd.set_as_af(sd.af_num(), sd_af_type);
        sd.set_speed(crate::gpio::Speed::VeryHigh);
-        let sub_block = WhichSubBlock::B;
+        let sub_block = S::WHICH;
        let request = dma.request();
-        SubBlock::new_inner(
+        Self::new_inner(
            peri,
            sub_block,
            None,
@@ -840,26 +713,6 @@ impl SubBlockB {
            config,
        )
    }
-}
-impl<'d, T: Instance, C: Channel, W: word::Word> SubBlock<'d, T, C, W> {
-    pub fn start(self: &mut Self) {
-        match self.ring_buffer {
-            RingBuffer::Writable(ref mut rb) => {
-                rb.start();
-            }
-            RingBuffer::Readable(ref mut rb) => {
-                rb.start();
-            }
-        }
-    }
-    fn is_transmitter(ring_buffer: &RingBuffer<C, W>) -> bool {
-        match ring_buffer {
-            RingBuffer::Writable(_) => true,
-            _ => false,
-        }
-    }
    fn new_inner(
        peri: impl Peripheral<P = T> + 'd,
@@ -929,7 +782,7 @@ impl<'d, T: Instance, C: Channel, W: word::Word> SubBlock<'d, T, C, W> {
                w.set_cpl(config.complement_format.cpl());
                w.set_muteval(config.mute_value.muteval());
                w.set_mutecnt(config.mute_detection_counter.0 as u8);
-                w.set_tris(config.is_high_impedenane_on_inactive_slot);
+                w.set_tris(config.is_high_impedance_on_inactive_slot);
            });
            ch.frcr().modify(|w| {
@@ -965,10 +818,31 @@ impl<'d, T: Instance, C: Channel, W: word::Word> SubBlock<'d, T, C, W> {
        }
    }
+    /// Start the SAI driver.
+    pub fn start(&mut self) {
+        match self.ring_buffer {
+            RingBuffer::Writable(ref mut rb) => {
+                rb.start();
+            }
+            RingBuffer::Readable(ref mut rb) => {
+                rb.start();
+            }
+        }
+    }
+    fn is_transmitter(ring_buffer: &RingBuffer<C, W>) -> bool {
+        match ring_buffer {
+            RingBuffer::Writable(_) => true,
+            _ => false,
+        }
+    }
+    /// Reset SAI operation.
    pub fn reset() {
        T::enable_and_reset();
    }
+    /// Flush.
    pub fn flush(&mut self) {
        let ch = T::REGS.ch(self.sub_block as usize);
        ch.cr1().modify(|w| w.set_saien(false));
@@ -983,19 +857,18 @@ impl<'d, T: Instance, C: Channel, W: word::Word> SubBlock<'d, T, C, W> {
        ch.cr1().modify(|w| w.set_saien(true));
    }
+    /// Enable or disable mute.
    pub fn set_mute(&mut self, value: bool) {
        let ch = T::REGS.ch(self.sub_block as usize);
        ch.cr2().modify(|w| w.set_mute(value));
    }
-    #[allow(dead_code)]
+    /// Write data to the SAI ringbuffer.
-    /// Reconfigures it with the supplied config.
+    ///
-    fn reconfigure(&mut self, _config: Config) {}
+    /// This appends the data to the buffer and returns immediately. The
+    /// data will be transmitted in the background.
-    pub fn get_current_config(&self) -> Config {
+    ///
-        Config::default()
+    /// If there's no space in the buffer, this waits until there is.
-    }
    pub async fn write(&mut self, data: &[W]) -> Result<(), Error> {
        match &mut self.ring_buffer {
            RingBuffer::Writable(buffer) => {
@@ -1006,6 +879,12 @@ impl<'d, T: Instance, C: Channel, W: word::Word> SubBlock<'d, T, C, W> {
        }
    }
+    /// Read data from the SAI ringbuffer.
+    ///
+    /// SAI is always receiving data in the background. This function pops already-received
+    /// data from the buffer.
+    ///
+    /// If there's less than `data.len()` data in the buffer, this waits until there is.
    pub async fn read(&mut self, data: &mut [W]) -> Result<(), Error> {
        match &mut self.ring_buffer {
            RingBuffer::Readable(buffer) => {
@@ -1017,7 +896,7 @@ impl<'d, T: Instance, C: Channel, W: word::Word> SubBlock<'d, T, C, W> {
    }
 }
-impl<'d, T: Instance, C: Channel, W: word::Word> Drop for SubBlock<'d, T, C, W> {
+impl<'d, T: Instance, C: Channel, W: word::Word> Drop for Sai<'d, T, C, W> {
    fn drop(&mut self) {
        let ch = T::REGS.ch(self.sub_block as usize);
        ch.cr1().modify(|w| w.set_saien(false));
@@ -1034,22 +913,43 @@ pub(crate) mod sealed {
    pub trait Instance {
        const REGS: Regs;
    }
+    #[derive(Copy, Clone)]
+    pub enum WhichSubBlock {
+        A = 0,
+        B = 1,
+    }
+    pub trait SubBlock {
+        const WHICH: WhichSubBlock;
+    }
 }
-pub trait Word: word::Word {}
+/// Sub-block instance trait.
+pub trait SubBlockInstance: sealed::SubBlock {}
+/// Sub-block A.
+pub enum A {}
+impl sealed::SubBlock for A {
+    const WHICH: WhichSubBlock = WhichSubBlock::A;
+}
+impl SubBlockInstance for A {}
+/// Sub-block B.
+pub enum B {}
+impl sealed::SubBlock for B {
+    const WHICH: WhichSubBlock = WhichSubBlock::B;
+}
+impl SubBlockInstance for B {}
+/// SAI instance trait.
 pub trait Instance: Peripheral<P = Self> + sealed::Instance + RccPeripheral {}
-pin_trait!(SckAPin, Instance);
+pin_trait!(SckPin, Instance, SubBlockInstance);
-pin_trait!(SckBPin, Instance);
+pin_trait!(FsPin, Instance, SubBlockInstance);
-pin_trait!(FsAPin, Instance);
+pin_trait!(SdPin, Instance, SubBlockInstance);
-pin_trait!(FsBPin, Instance);
+pin_trait!(MclkPin, Instance, SubBlockInstance);
-pin_trait!(SdAPin, Instance);
-pin_trait!(SdBPin, Instance);
+dma_trait!(Dma, Instance, SubBlockInstance);
-pin_trait!(MclkAPin, Instance);
-pin_trait!(MclkBPin, Instance);
-dma_trait!(DmaA, Instance);
-dma_trait!(DmaB, Instance);
 foreach_peripheral!(
    (sai, $inst:ident) => {
@@ -1060,13 +960,3 @@ foreach_peripheral!(
        impl Instance for peripherals::$inst {}
    };
 );
-impl<'d, T: Instance> SetConfig for Sai<'d, T> {
-    type Config = Config;
-    type ConfigError = ();
-    fn set_config(&mut self, _config: &Self::Config) -> Result<(), ()> {
-        // self.reconfigure(*config);
-        Ok(())
-    }
-}
diff --git a/embassy-stm32/src/sdmmc/mod.rs b/embassy-stm32/src/sdmmc/mod.rs
index 27a12062c..debe26c88 100644
--- a/embassy-stm32/src/sdmmc/mod.rs
+++ b/embassy-stm32/src/sdmmc/mod.rs
@@ -1,3 +1,4 @@
+//! Secure Digital / MultiMedia Card (SDMMC)
 #![macro_use]
 use core::default::Default;
@@ -53,6 +54,7 @@ const SD_INIT_FREQ: Hertz = Hertz(400_000);
 /// The signalling scheme used on the SDMMC bus
 #[non_exhaustive]
+#[allow(missing_docs)]
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Signalling {
@@ -69,6 +71,9 @@ impl Default for Signalling {
    }
 }
+/// Aligned data block for SDMMC transfers.
+///
+/// This is a 512-byte array, aligned to 4 bytes to satisfy DMA requirements.
 #[repr(align(4))]
 #[derive(Debug, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
@@ -93,17 +98,23 @@ impl DerefMut for DataBlock {
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Error {
+    /// Timeout reported by the hardware
    Timeout,
+    /// Timeout reported by the software driver.
    SoftwareTimeout,
+    /// Unsupported card version.
    UnsupportedCardVersion,
+    /// Unsupported card type.
    UnsupportedCardType,
+    /// CRC error.
    Crc,
-    DataCrcFail,
+    /// No card inserted.
-    RxOverFlow,
    NoCard,
+    /// Bad clock supplied to the SDMMC peripheral.
    BadClock,
+    /// Signaling switch failed.
    SignalingSwitchFailed,
-    PeripheralBusy,
+    /// ST bit error.
    #[cfg(sdmmc_v1)]
    StBitErr,
 }
@@ -282,6 +293,7 @@ pub struct Sdmmc<'d, T: Instance, Dma: SdmmcDma<T> = NoDma> {
 #[cfg(sdmmc_v1)]
 impl<'d, T: Instance, Dma: SdmmcDma<T>> Sdmmc<'d, T, Dma> {
+    /// Create a new SDMMC driver, with 1 data lane.
    pub fn new_1bit(
        sdmmc: impl Peripheral<P = T> + 'd,
        _irq: impl interrupt::typelevel::Binding<T::Interrupt, InterruptHandler<T>> + 'd,
@@ -316,6 +328,7 @@ impl<'d, T: Instance, Dma: SdmmcDma<T>> Sdmmc<'d, T, Dma> {
        )
    }
+    /// Create a new SDMMC driver, with 4 data lanes.
    pub fn new_4bit(
        sdmmc: impl Peripheral<P = T> + 'd,
        _irq: impl interrupt::typelevel::Binding<T::Interrupt, InterruptHandler<T>> + 'd,
@@ -362,6 +375,7 @@ impl<'d, T: Instance, Dma: SdmmcDma<T>> Sdmmc<'d, T, Dma> {
 #[cfg(sdmmc_v2)]
 impl<'d, T: Instance> Sdmmc<'d, T, NoDma> {
+    /// Create a new SDMMC driver, with 1 data lane.
    pub fn new_1bit(
        sdmmc: impl Peripheral<P = T> + 'd,
        _irq: impl interrupt::typelevel::Binding<T::Interrupt, InterruptHandler<T>> + 'd,
@@ -395,6 +409,7 @@ impl<'d, T: Instance> Sdmmc<'d, T, NoDma> {
        )
    }
+    /// Create a new SDMMC driver, with 4 data lanes.
    pub fn new_4bit(
        sdmmc: impl Peripheral<P = T> + 'd,
        _irq: impl interrupt::typelevel::Binding<T::Interrupt, InterruptHandler<T>> + 'd,
@@ -496,7 +511,7 @@ impl<'d, T: Instance, Dma: SdmmcDma<T> + 'd> Sdmmc<'d, T, Dma> {
    }
    /// Data transfer is in progress
-    #[inline(always)]
+    #[inline]
    fn data_active() -> bool {
        let regs = T::regs();
@@ -508,7 +523,7 @@ impl<'d, T: Instance, Dma: SdmmcDma<T> + 'd> Sdmmc<'d, T, Dma> {
    }
    /// Coammand transfer is in progress
-    #[inline(always)]
+    #[inline]
    fn cmd_active() -> bool {
        let regs = T::regs();
@@ -520,7 +535,7 @@ impl<'d, T: Instance, Dma: SdmmcDma<T> + 'd> Sdmmc<'d, T, Dma> {
    }
    /// Wait idle on CMDACT, RXACT and TXACT (v1) or DOSNACT and CPSMACT (v2)
-    #[inline(always)]
+    #[inline]
    fn wait_idle() {
        while Self::data_active() || Self::cmd_active() {}
    }
@@ -836,7 +851,7 @@ impl<'d, T: Instance, Dma: SdmmcDma<T> + 'd> Sdmmc<'d, T, Dma> {
    }
    /// Clear flags in interrupt clear register
-    #[inline(always)]
+    #[inline]
    fn clear_interrupt_flags() {
        let regs = T::regs();
        regs.icr().write(|w| {
@@ -1151,7 +1166,8 @@ impl<'d, T: Instance, Dma: SdmmcDma<T> + 'd> Sdmmc<'d, T, Dma> {
        Ok(())
    }
-    #[inline(always)]
+    /// Read a data block.
+    #[inline]
    pub async fn read_block(&mut self, block_idx: u32, buffer: &mut DataBlock) -> Result<(), Error> {
        let card_capacity = self.card()?.card_type;
@@ -1203,6 +1219,7 @@ impl<'d, T: Instance, Dma: SdmmcDma<T> + 'd> Sdmmc<'d, T, Dma> {
        res
    }
+    /// Write a data block.
    pub async fn write_block(&mut self, block_idx: u32, buffer: &DataBlock) -> Result<(), Error> {
        let card = self.card.as_mut().ok_or(Error::NoCard)?;
@@ -1282,7 +1299,7 @@ impl<'d, T: Instance, Dma: SdmmcDma<T> + 'd> Sdmmc<'d, T, Dma> {
    ///
    /// Returns Error::NoCard if [`init_card`](#method.init_card)
    /// has not previously succeeded
-    #[inline(always)]
+    #[inline]
    pub fn card(&self) -> Result<&Card, Error> {
        self.card.as_ref().ok_or(Error::NoCard)
    }
@@ -1418,7 +1435,9 @@ pub(crate) mod sealed {
    pub trait Pins<T: Instance> {}
 }
+/// SDMMC instance trait.
 pub trait Instance: sealed::Instance + RccPeripheral + 'static {}
 pin_trait!(CkPin, Instance);
 pin_trait!(CmdPin, Instance);
 pin_trait!(D0Pin, Instance);
@@ -1433,7 +1452,10 @@ pin_trait!(D7Pin, Instance);
 #[cfg(sdmmc_v1)]
 dma_trait!(SdmmcDma, Instance);
-// SDMMCv2 uses internal DMA
+/// DMA instance trait.
+///
+/// This is only implemented for `NoDma`, since SDMMCv2 has DMA built-in, instead of
+/// using ST's system-wide DMA peripheral.
 #[cfg(sdmmc_v2)]
 pub trait SdmmcDma<T: Instance> {}
 #[cfg(sdmmc_v2)]
@@ -1516,53 +1538,3 @@ foreach_peripheral!(
        impl Instance for peripherals::$inst {}
    };
 );
-#[cfg(feature = "embedded-sdmmc")]
-mod sdmmc_rs {
-    use embedded_sdmmc::{Block, BlockCount, BlockDevice, BlockIdx};
-    use super::*;
-    impl<'d, T: Instance, Dma: SdmmcDma<T>> BlockDevice for Sdmmc<'d, T, Dma> {
-        type Error = Error;
-        async fn read(
-            &mut self,
-            blocks: &mut [Block],
-            start_block_idx: BlockIdx,
-            _reason: &str,
-        ) -> Result<(), Self::Error> {
-            let mut address = start_block_idx.0;
-            for block in blocks.iter_mut() {
-                let block: &mut [u8; 512] = &mut block.contents;
-                // NOTE(unsafe) Block uses align(4)
-                let block = unsafe { &mut *(block as *mut _ as *mut DataBlock) };
-                self.read_block(address, block).await?;
-                address += 1;
-            }
-            Ok(())
-        }
-        async fn write(&mut self, blocks: &[Block], start_block_idx: BlockIdx) -> Result<(), Self::Error> {
-            let mut address = start_block_idx.0;
-            for block in blocks.iter() {
-                let block: &[u8; 512] = &block.contents;
-                // NOTE(unsafe) DataBlock uses align 4
-                let block = unsafe { &*(block as *const _ as *const DataBlock) };
-                self.write_block(address, block).await?;
-                address += 1;
-            }
-            Ok(())
-        }
-        fn num_blocks(&self) -> Result<BlockCount, Self::Error> {
-            let card = self.card()?;
-            let count = card.csd.block_count();
-            Ok(BlockCount(count))
-        }
-    }
-}
diff --git a/embassy-stm32/src/spi/mod.rs b/embassy-stm32/src/spi/mod.rs
index 92599c75e..23f027e70 100644
--- a/embassy-stm32/src/spi/mod.rs
+++ b/embassy-stm32/src/spi/mod.rs
@@ -1,3 +1,4 @@
+//! Serial Peripheral Interface (SPI)
 #![macro_use]
 use core::ptr;
@@ -15,27 +16,38 @@ use crate::rcc::RccPeripheral;
 use crate::time::Hertz;
 use crate::{peripherals, Peripheral};
+/// SPI error.
 #[derive(Debug, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Error {
+    /// Invalid framing.
    Framing,
+    /// CRC error (only if hardware CRC checking is enabled).
    Crc,
+    /// Mode fault
    ModeFault,
+    /// Overrun.
    Overrun,
 }
-// TODO move upwards in the tree
+/// SPI bit order
 #[derive(Copy, Clone)]
 pub enum BitOrder {
+    /// Least significant bit first.
    LsbFirst,
+    /// Most significant bit first.
    MsbFirst,
 }
+/// SPI configuration.
 #[non_exhaustive]
 #[derive(Copy, Clone)]
 pub struct Config {
+    /// SPI mode.
    pub mode: Mode,
+    /// Bit order.
    pub bit_order: BitOrder,
+    /// Clock frequency.
    pub frequency: Hertz,
 }
@@ -72,6 +84,7 @@ impl Config {
    }
 }
+/// SPI driver.
 pub struct Spi<'d, T: Instance, Tx, Rx> {
    _peri: PeripheralRef<'d, T>,
    sck: Option<PeripheralRef<'d, AnyPin>>,
@@ -83,6 +96,7 @@ pub struct Spi<'d, T: Instance, Tx, Rx> {
 }
 impl<'d, T: Instance, Tx, Rx> Spi<'d, T, Tx, Rx> {
+    /// Create a new SPI driver.
    pub fn new(
        peri: impl Peripheral<P = T> + 'd,
        sck: impl Peripheral<P = impl SckPin<T>> + 'd,
@@ -117,6 +131,7 @@ impl<'d, T: Instance, Tx, Rx> Spi<'d, T, Tx, Rx> {
        )
    }
+    /// Create a new SPI driver, in RX-only mode (only MISO pin, no MOSI).
    pub fn new_rxonly(
        peri: impl Peripheral<P = T> + 'd,
        sck: impl Peripheral<P = impl SckPin<T>> + 'd,
@@ -142,6 +157,7 @@ impl<'d, T: Instance, Tx, Rx> Spi<'d, T, Tx, Rx> {
        )
    }
+    /// Create a new SPI driver, in TX-only mode (only MOSI pin, no MISO).
    pub fn new_txonly(
        peri: impl Peripheral<P = T> + 'd,
        sck: impl Peripheral<P = impl SckPin<T>> + 'd,
@@ -167,6 +183,9 @@ impl<'d, T: Instance, Tx, Rx> Spi<'d, T, Tx, Rx> {
        )
    }
+    /// Create a new SPI driver, in TX-only mode, without SCK pin.
+    ///
+    /// This can be useful for bit-banging non-SPI protocols.
    pub fn new_txonly_nosck(
        peri: impl Peripheral<P = T> + 'd,
        mosi: impl Peripheral<P = impl MosiPin<T>> + 'd,
@@ -292,7 +311,7 @@ impl<'d, T: Instance, Tx, Rx> Spi<'d, T, Tx, Rx> {
                w.set_ssom(vals::Ssom::ASSERTED);
                w.set_midi(0);
                w.set_mssi(0);
-                w.set_afcntr(vals::Afcntr::CONTROLLED);
+                w.set_afcntr(true);
                w.set_ssiop(vals::Ssiop::ACTIVEHIGH);
            });
            T::REGS.cfg1().modify(|w| {
@@ -354,6 +373,7 @@ impl<'d, T: Instance, Tx, Rx> Spi<'d, T, Tx, Rx> {
        Ok(())
    }
+    /// Get current SPI configuration.
    pub fn get_current_config(&self) -> Config {
        #[cfg(any(spi_v1, spi_f1, spi_v2))]
        let cfg = T::REGS.cr1().read();
@@ -443,6 +463,7 @@ impl<'d, T: Instance, Tx, Rx> Spi<'d, T, Tx, Rx> {
        self.current_word_size = word_size;
    }
+    /// SPI write, using DMA.
    pub async fn write<W: Word>(&mut self, data: &[W]) -> Result<(), Error>
    where
        Tx: TxDma<T>,
@@ -476,6 +497,7 @@ impl<'d, T: Instance, Tx, Rx> Spi<'d, T, Tx, Rx> {
        Ok(())
    }
+    /// SPI read, using DMA.
    pub async fn read<W: Word>(&mut self, data: &mut [W]) -> Result<(), Error>
    where
        Tx: TxDma<T>,
@@ -579,6 +601,12 @@ impl<'d, T: Instance, Tx, Rx> Spi<'d, T, Tx, Rx> {
        Ok(())
    }
+    /// Bidirectional transfer, using DMA.
+    ///
+    /// This transfers both buffers at the same time, so it is NOT equivalent to `write` followed by `read`.
+    ///
+    /// The transfer runs for `max(read.len(), write.len())` bytes. If `read` is shorter extra bytes are ignored.
+    /// If `write` is shorter it is padded with zero bytes.
    pub async fn transfer<W: Word>(&mut self, read: &mut [W], write: &[W]) -> Result<(), Error>
    where
        Tx: TxDma<T>,
@@ -587,6 +615,9 @@ impl<'d, T: Instance, Tx, Rx> Spi<'d, T, Tx, Rx> {
        self.transfer_inner(read, write).await
    }
+    /// In-place bidirectional transfer, using DMA.
+    ///
+    /// This writes the contents of `data` on MOSI, and puts the received data on MISO in `data`, at the same time.
    pub async fn transfer_in_place<W: Word>(&mut self, data: &mut [W]) -> Result<(), Error>
    where
        Tx: TxDma<T>,
@@ -595,6 +626,7 @@ impl<'d, T: Instance, Tx, Rx> Spi<'d, T, Tx, Rx> {
        self.transfer_inner(data, data).await
    }
+    /// Blocking write.
    pub fn blocking_write<W: Word>(&mut self, words: &[W]) -> Result<(), Error> {
        T::REGS.cr1().modify(|w| w.set_spe(true));
        flush_rx_fifo(T::REGS);
@@ -605,6 +637,7 @@ impl<'d, T: Instance, Tx, Rx> Spi<'d, T, Tx, Rx> {
        Ok(())
    }
+    /// Blocking read.
    pub fn blocking_read<W: Word>(&mut self, words: &mut [W]) -> Result<(), Error> {
        T::REGS.cr1().modify(|w| w.set_spe(true));
        flush_rx_fifo(T::REGS);
@@ -615,6 +648,9 @@ impl<'d, T: Instance, Tx, Rx> Spi<'d, T, Tx, Rx> {
        Ok(())
    }
+    /// Blocking in-place bidirectional transfer.
+    ///
+    /// This writes the contents of `data` on MOSI, and puts the received data on MISO in `data`, at the same time.
    pub fn blocking_transfer_in_place<W: Word>(&mut self, words: &mut [W]) -> Result<(), Error> {
        T::REGS.cr1().modify(|w| w.set_spe(true));
        flush_rx_fifo(T::REGS);
@@ -625,6 +661,12 @@ impl<'d, T: Instance, Tx, Rx> Spi<'d, T, Tx, Rx> {
        Ok(())
    }
+    /// Blocking bidirectional transfer.
+    ///
+    /// This transfers both buffers at the same time, so it is NOT equivalent to `write` followed by `read`.
+    ///
+    /// The transfer runs for `max(read.len(), write.len())` bytes. If `read` is shorter extra bytes are ignored.
+    /// If `write` is shorter it is padded with zero bytes.
    pub fn blocking_transfer<W: Word>(&mut self, read: &mut [W], write: &[W]) -> Result<(), Error> {
        T::REGS.cr1().modify(|w| w.set_spe(true));
        flush_rx_fifo(T::REGS);
@@ -945,6 +987,7 @@ pub(crate) mod sealed {
    }
 }
+/// Word sizes usable for SPI.
 pub trait Word: word::Word + sealed::Word {}
 macro_rules! impl_word {
@@ -1024,7 +1067,9 @@ mod word_impl {
    impl_word!(u32, 32 - 1);
 }
+/// SPI instance trait.
 pub trait Instance: Peripheral<P = Self> + sealed::Instance + RccPeripheral {}
 pin_trait!(SckPin, Instance);
 pin_trait!(MosiPin, Instance);
 pin_trait!(MisoPin, Instance);
diff --git a/embassy-stm32/src/time.rs b/embassy-stm32/src/time.rs
index a0bc33944..17690aefc 100644
--- a/embassy-stm32/src/time.rs
+++ b/embassy-stm32/src/time.rs
@@ -8,14 +8,17 @@ use core::ops::{Div, Mul};
 pub struct Hertz(pub u32);
 impl Hertz {
+    /// Create a `Hertz` from the given hertz.
    pub const fn hz(hertz: u32) -> Self {
        Self(hertz)
    }
+    /// Create a `Hertz` from the given kilohertz.
    pub const fn khz(kilohertz: u32) -> Self {
        Self(kilohertz * 1_000)
    }
+    /// Create a `Hertz` from the given megahertz.
    pub const fn mhz(megahertz: u32) -> Self {
        Self(megahertz * 1_000_000)
    }
diff --git a/embassy-stm32/src/time_driver.rs b/embassy-stm32/src/time_driver.rs
index e2a4cc4da..9981800b2 100644
--- a/embassy-stm32/src/time_driver.rs
+++ b/embassy-stm32/src/time_driver.rs
@@ -43,7 +43,10 @@ type T = peripherals::TIM3;
 type T = peripherals::TIM4;
 #[cfg(time_driver_tim5)]
 type T = peripherals::TIM5;
+#[cfg(time_driver_tim9)]
+type T = peripherals::TIM9;
+#[cfg(time_driver_tim11)]
+type T = peripherals::TIM11;
 #[cfg(time_driver_tim12)]
 type T = peripherals::TIM12;
 #[cfg(time_driver_tim15)]
@@ -82,6 +85,22 @@ foreach_interrupt! {
            DRIVER.on_interrupt()
        }
    };
+    (TIM9, timer, $block:ident, UP, $irq:ident) => {
+        #[cfg(time_driver_tim9)]
+        #[cfg(feature = "rt")]
+        #[interrupt]
+        fn $irq() {
+            DRIVER.on_interrupt()
+        }
+    };
+    (TIM11, timer, $block:ident, UP, $irq:ident) => {
+        #[cfg(time_driver_tim11)]
+        #[cfg(feature = "rt")]
+        #[interrupt]
+        fn $irq() {
+            DRIVER.on_interrupt()
+        }
+    };
    (TIM12, timer, $block:ident, UP, $irq:ident) => {
        #[cfg(time_driver_tim12)]
        #[cfg(feature = "rt")]
@@ -455,16 +474,29 @@ impl Driver for RtcDriver {
                return false;
            }
-            let safe_timestamp = timestamp.max(t + 3);
            // Write the CCR value regardless of whether we're going to enable it now or not.
            // This way, when we enable it later, the right value is already set.
-            r.ccr(n + 1).write(|w| w.set_ccr(safe_timestamp as u16));
+            r.ccr(n + 1).write(|w| w.set_ccr(timestamp as u16));
            // Enable it if it'll happen soon. Otherwise, `next_period` will enable it.
            let diff = timestamp - t;
            r.dier().modify(|w| w.set_ccie(n + 1, diff < 0xc000));
+            // Reevaluate if the alarm timestamp is still in the future
+            let t = self.now();
+            if timestamp <= t {
+                // If alarm timestamp has passed since we set it, we have a race condition and
+                // the alarm may or may not have fired.
+                // Disarm the alarm and return `false` to indicate that.
+                // It is the caller's responsibility to handle this ambiguity.
+                r.dier().modify(|w| w.set_ccie(n + 1, false));
+                alarm.timestamp.set(u64::MAX);
+                return false;
+            }
+            // We're confident the alarm will ring in the future.
            true
        })
    }
diff --git a/embassy-stm32/src/timer/complementary_pwm.rs b/embassy-stm32/src/timer/complementary_pwm.rs
index 6654366cd..71d7110b5 100644
--- a/embassy-stm32/src/timer/complementary_pwm.rs
+++ b/embassy-stm32/src/timer/complementary_pwm.rs
@@ -1,3 +1,5 @@
+//! PWM driver with complementary output support.
 use core::marker::PhantomData;
 use embassy_hal_internal::{into_ref, PeripheralRef};
@@ -11,15 +13,19 @@ use crate::gpio::{AnyPin, OutputType};
 use crate::time::Hertz;
 use crate::Peripheral;
-pub struct ComplementaryPwmPin<'d, Perip, Channel> {
+/// Complementary PWM pin wrapper.
+///
+/// This wraps a pin to make it usable with PWM.
+pub struct ComplementaryPwmPin<'d, T, C> {
    _pin: PeripheralRef<'d, AnyPin>,
-    phantom: PhantomData<(Perip, Channel)>,
+    phantom: PhantomData<(T, C)>,
 }
 macro_rules! complementary_channel_impl {
    ($new_chx:ident, $channel:ident, $pin_trait:ident) => {
-        impl<'d, Perip: CaptureCompare16bitInstance> ComplementaryPwmPin<'d, Perip, $channel> {
+        impl<'d, T: CaptureCompare16bitInstance> ComplementaryPwmPin<'d, T, $channel> {
-            pub fn $new_chx(pin: impl Peripheral<P = impl $pin_trait<Perip>> + 'd, output_type: OutputType) -> Self {
+            #[doc = concat!("Create a new ", stringify!($channel), " complementary PWM pin instance.")]
+            pub fn $new_chx(pin: impl Peripheral<P = impl $pin_trait<T>> + 'd, output_type: OutputType) -> Self {
                into_ref!(pin);
                critical_section::with(|_| {
                    pin.set_low();
@@ -41,11 +47,13 @@ complementary_channel_impl!(new_ch2, Ch2, Channel2ComplementaryPin);
 complementary_channel_impl!(new_ch3, Ch3, Channel3ComplementaryPin);
 complementary_channel_impl!(new_ch4, Ch4, Channel4ComplementaryPin);
+/// PWM driver with support for standard and complementary outputs.
 pub struct ComplementaryPwm<'d, T> {
    inner: PeripheralRef<'d, T>,
 }
 impl<'d, T: ComplementaryCaptureCompare16bitInstance> ComplementaryPwm<'d, T> {
+    /// Create a new complementary PWM driver.
    pub fn new(
        tim: impl Peripheral<P = T> + 'd,
        _ch1: Option<PwmPin<'d, T, Ch1>>,
@@ -70,7 +78,7 @@ impl<'d, T: ComplementaryCaptureCompare16bitInstance> ComplementaryPwm<'d, T> {
        let mut this = Self { inner: tim };
        this.inner.set_counting_mode(counting_mode);
-        this.set_freq(freq);
+        this.set_frequency(freq);
        this.inner.start();
        this.inner.enable_outputs();
@@ -86,17 +94,23 @@ impl<'d, T: ComplementaryCaptureCompare16bitInstance> ComplementaryPwm<'d, T> {
        this
    }
+    /// Enable the given channel.
    pub fn enable(&mut self, channel: Channel) {
        self.inner.enable_channel(channel, true);
        self.inner.enable_complementary_channel(channel, true);
    }
+    /// Disable the given channel.
    pub fn disable(&mut self, channel: Channel) {
        self.inner.enable_complementary_channel(channel, false);
        self.inner.enable_channel(channel, false);
    }
-    pub fn set_freq(&mut self, freq: Hertz) {
+    /// Set PWM frequency.
+    ///
+    /// Note: when you call this, the max duty value changes, so you will have to
+    /// call `set_duty` on all channels with the duty calculated based on the new max duty.
+    pub fn set_frequency(&mut self, freq: Hertz) {
        let multiplier = if self.inner.get_counting_mode().is_center_aligned() {
            2u8
        } else {
@@ -105,15 +119,22 @@ impl<'d, T: ComplementaryCaptureCompare16bitInstance> ComplementaryPwm<'d, T> {
        self.inner.set_frequency(freq * multiplier);
    }
+    /// Get max duty value.
+    ///
+    /// This value depends on the configured frequency and the timer's clock rate from RCC.
    pub fn get_max_duty(&self) -> u16 {
        self.inner.get_max_compare_value() + 1
    }
+    /// Set the duty for a given channel.
+    ///
+    /// The value ranges from 0 for 0% duty, to [`get_max_duty`](Self::get_max_duty) for 100% duty, both included.
    pub fn set_duty(&mut self, channel: Channel, duty: u16) {
        assert!(duty <= self.get_max_duty());
        self.inner.set_compare_value(channel, duty)
    }
+    /// Set the output polarity for a given channel.
    pub fn set_polarity(&mut self, channel: Channel, polarity: OutputPolarity) {
        self.inner.set_output_polarity(channel, polarity);
        self.inner.set_complementary_output_polarity(channel, polarity);
diff --git a/embassy-stm32/src/timer/mod.rs b/embassy-stm32/src/timer/mod.rs
index 2313a5b94..74120adad 100644
--- a/embassy-stm32/src/timer/mod.rs
+++ b/embassy-stm32/src/timer/mod.rs
@@ -1,3 +1,5 @@
+//! Timers, PWM, quadrature decoder.
 pub mod complementary_pwm;
 pub mod qei;
 pub mod simple_pwm;
@@ -8,23 +10,34 @@ use crate::interrupt;
 use crate::rcc::RccPeripheral;
 use crate::time::Hertz;
+/// Low-level timer access.
 #[cfg(feature = "unstable-pac")]
 pub mod low_level {
    pub use super::sealed::*;
 }
 pub(crate) mod sealed {
    use super::*;
+    /// Basic 16-bit timer instance.
    pub trait Basic16bitInstance: RccPeripheral {
+        /// Interrupt for this timer.
        type Interrupt: interrupt::typelevel::Interrupt;
+        /// Get access to the basic 16bit timer registers.
+        ///
+        /// Note: This works even if the timer is more capable, because registers
+        /// for the less capable timers are a subset. This allows writing a driver
+        /// for a given set of capabilities, and having it transparently work with
+        /// more capable timers.
        fn regs() -> crate::pac::timer::TimBasic;
+        /// Start the timer.
        fn start(&mut self) {
            Self::regs().cr1().modify(|r| r.set_cen(true));
        }
+        /// Stop the timer.
        fn stop(&mut self) {
            Self::regs().cr1().modify(|r| r.set_cen(false));
        }
@@ -60,6 +73,9 @@ pub(crate) mod sealed {
            regs.cr1().modify(|r| r.set_urs(vals::Urs::ANYEVENT));
        }
+        /// Clear update interrupt.
+        ///
+        /// Returns whether the update interrupt flag was set.
        fn clear_update_interrupt(&mut self) -> bool {
            let regs = Self::regs();
            let sr = regs.sr().read();
@@ -73,14 +89,17 @@ pub(crate) mod sealed {
            }
        }
+        /// Enable/disable the update interrupt.
        fn enable_update_interrupt(&mut self, enable: bool) {
            Self::regs().dier().write(|r| r.set_uie(enable));
        }
-        fn set_autoreload_preload(&mut self, enable: vals::Arpe) {
+        /// Enable/disable autoreload preload.
+        fn set_autoreload_preload(&mut self, enable: bool) {
            Self::regs().cr1().modify(|r| r.set_arpe(enable));
        }
+        /// Get the timer frequency.
        fn get_frequency(&self) -> Hertz {
            let timer_f = Self::frequency();
@@ -92,9 +111,17 @@ pub(crate) mod sealed {
        }
    }
+    /// Gneral-purpose 16-bit timer instance.
    pub trait GeneralPurpose16bitInstance: Basic16bitInstance {
+        /// Get access to the general purpose 16bit timer registers.
+        ///
+        /// Note: This works even if the timer is more capable, because registers
+        /// for the less capable timers are a subset. This allows writing a driver
+        /// for a given set of capabilities, and having it transparently work with
+        /// more capable timers.
        fn regs_gp16() -> crate::pac::timer::TimGp16;
+        /// Set counting mode.
        fn set_counting_mode(&mut self, mode: CountingMode) {
            let (cms, dir) = mode.into();
@@ -107,19 +134,29 @@ pub(crate) mod sealed {
            Self::regs_gp16().cr1().modify(|r| r.set_cms(cms))
        }
+        /// Get counting mode.
        fn get_counting_mode(&self) -> CountingMode {
            let cr1 = Self::regs_gp16().cr1().read();
            (cr1.cms(), cr1.dir()).into()
        }
+        /// Set clock divider.
        fn set_clock_division(&mut self, ckd: vals::Ckd) {
            Self::regs_gp16().cr1().modify(|r| r.set_ckd(ckd));
        }
    }
+    /// Gneral-purpose 32-bit timer instance.
    pub trait GeneralPurpose32bitInstance: GeneralPurpose16bitInstance {
+        /// Get access to the general purpose 32bit timer registers.
+        ///
+        /// Note: This works even if the timer is more capable, because registers
+        /// for the less capable timers are a subset. This allows writing a driver
+        /// for a given set of capabilities, and having it transparently work with
+        /// more capable timers.
        fn regs_gp32() -> crate::pac::timer::TimGp32;
+        /// Set timer frequency.
        fn set_frequency(&mut self, frequency: Hertz) {
            let f = frequency.0;
            assert!(f > 0);
@@ -137,6 +174,7 @@ pub(crate) mod sealed {
            regs.cr1().modify(|r| r.set_urs(vals::Urs::ANYEVENT));
        }
+        /// Get timer frequency.
        fn get_frequency(&self) -> Hertz {
            let timer_f = Self::frequency();
@@ -148,141 +186,177 @@ pub(crate) mod sealed {
        }
    }
+    /// Advanced control timer instance.
    pub trait AdvancedControlInstance: GeneralPurpose16bitInstance {
+        /// Get access to the advanced timer registers.
        fn regs_advanced() -> crate::pac::timer::TimAdv;
    }
+    /// Capture/Compare 16-bit timer instance.
    pub trait CaptureCompare16bitInstance: GeneralPurpose16bitInstance {
+        /// Set input capture filter.
        fn set_input_capture_filter(&mut self, channel: Channel, icf: vals::Icf) {
-            let raw_channel = channel.raw();
+            let raw_channel = channel.index();
            Self::regs_gp16()
                .ccmr_input(raw_channel / 2)
                .modify(|r| r.set_icf(raw_channel % 2, icf));
        }
+        /// Clear input interrupt.
        fn clear_input_interrupt(&mut self, channel: Channel) {
-            Self::regs_gp16().sr().modify(|r| r.set_ccif(channel.raw(), false));
+            Self::regs_gp16().sr().modify(|r| r.set_ccif(channel.index(), false));
        }
+        /// Enable input interrupt.
        fn enable_input_interrupt(&mut self, channel: Channel, enable: bool) {
-            Self::regs_gp16().dier().modify(|r| r.set_ccie(channel.raw(), enable));
+            Self::regs_gp16().dier().modify(|r| r.set_ccie(channel.index(), enable));
        }
+        /// Set input capture prescaler.
        fn set_input_capture_prescaler(&mut self, channel: Channel, factor: u8) {
-            let raw_channel = channel.raw();
+            let raw_channel = channel.index();
            Self::regs_gp16()
                .ccmr_input(raw_channel / 2)
                .modify(|r| r.set_icpsc(raw_channel % 2, factor));
        }
+        /// Set input TI selection.
        fn set_input_ti_selection(&mut self, channel: Channel, tisel: InputTISelection) {
-            let raw_channel = channel.raw();
+            let raw_channel = channel.index();
            Self::regs_gp16()
                .ccmr_input(raw_channel / 2)
                .modify(|r| r.set_ccs(raw_channel % 2, tisel.into()));
        }
+        /// Set input capture mode.
        fn set_input_capture_mode(&mut self, channel: Channel, mode: InputCaptureMode) {
            Self::regs_gp16().ccer().modify(|r| match mode {
                InputCaptureMode::Rising => {
-                    r.set_ccnp(channel.raw(), false);
+                    r.set_ccnp(channel.index(), false);
-                    r.set_ccp(channel.raw(), false);
+                    r.set_ccp(channel.index(), false);
                }
                InputCaptureMode::Falling => {
-                    r.set_ccnp(channel.raw(), false);
+                    r.set_ccnp(channel.index(), false);
-                    r.set_ccp(channel.raw(), true);
+                    r.set_ccp(channel.index(), true);
                }
                InputCaptureMode::BothEdges => {
-                    r.set_ccnp(channel.raw(), true);
+                    r.set_ccnp(channel.index(), true);
-                    r.set_ccp(channel.raw(), true);
+                    r.set_ccp(channel.index(), true);
                }
            });
        }
+        /// Enable timer outputs.
        fn enable_outputs(&mut self);
+        /// Set output compare mode.
        fn set_output_compare_mode(&mut self, channel: Channel, mode: OutputCompareMode) {
            let r = Self::regs_gp16();
-            let raw_channel: usize = channel.raw();
+            let raw_channel: usize = channel.index();
            r.ccmr_output(raw_channel / 2)
                .modify(|w| w.set_ocm(raw_channel % 2, mode.into()));
        }
+        /// Set output polarity.
        fn set_output_polarity(&mut self, channel: Channel, polarity: OutputPolarity) {
            Self::regs_gp16()
                .ccer()
-                .modify(|w| w.set_ccp(channel.raw(), polarity.into()));
+                .modify(|w| w.set_ccp(channel.index(), polarity.into()));
        }
+        /// Enable/disable a channel.
        fn enable_channel(&mut self, channel: Channel, enable: bool) {
-            Self::regs_gp16().ccer().modify(|w| w.set_cce(channel.raw(), enable));
+            Self::regs_gp16().ccer().modify(|w| w.set_cce(channel.index(), enable));
        }
+        /// Set compare value for a channel.
        fn set_compare_value(&mut self, channel: Channel, value: u16) {
-            Self::regs_gp16().ccr(channel.raw()).modify(|w| w.set_ccr(value));
+            Self::regs_gp16().ccr(channel.index()).modify(|w| w.set_ccr(value));
        }
+        /// Get capture value for a channel.
        fn get_capture_value(&mut self, channel: Channel) -> u16 {
-            Self::regs_gp16().ccr(channel.raw()).read().ccr()
+            Self::regs_gp16().ccr(channel.index()).read().ccr()
        }
+        /// Get max compare value. This depends on the timer frequency and the clock frequency from RCC.
        fn get_max_compare_value(&self) -> u16 {
            Self::regs_gp16().arr().read().arr()
        }
+        /// Get compare value for a channel.
        fn get_compare_value(&self, channel: Channel) -> u16 {
-            Self::regs_gp16().ccr(channel.raw()).read().ccr()
+            Self::regs_gp16().ccr(channel.index()).read().ccr()
        }
    }
+    /// Capture/Compare 16-bit timer instance with complementary pin support.
    pub trait ComplementaryCaptureCompare16bitInstance: CaptureCompare16bitInstance + AdvancedControlInstance {
+        /// Set complementary output polarity.
        fn set_complementary_output_polarity(&mut self, channel: Channel, polarity: OutputPolarity) {
            Self::regs_advanced()
                .ccer()
-                .modify(|w| w.set_ccnp(channel.raw(), polarity.into()));
+                .modify(|w| w.set_ccnp(channel.index(), polarity.into()));
        }
+        /// Set clock divider for the dead time.
        fn set_dead_time_clock_division(&mut self, value: vals::Ckd) {
            Self::regs_advanced().cr1().modify(|w| w.set_ckd(value));
        }
+        /// Set dead time, as a fraction of the max duty value.
        fn set_dead_time_value(&mut self, value: u8) {
            Self::regs_advanced().bdtr().modify(|w| w.set_dtg(value));
        }
+        /// Enable/disable a complementary channel.
        fn enable_complementary_channel(&mut self, channel: Channel, enable: bool) {
            Self::regs_advanced()
                .ccer()
-                .modify(|w| w.set_ccne(channel.raw(), enable));
+                .modify(|w| w.set_ccne(channel.index(), enable));
        }
    }
+    /// Capture/Compare 32-bit timer instance.
    pub trait CaptureCompare32bitInstance: GeneralPurpose32bitInstance + CaptureCompare16bitInstance {
+        /// Set comapre value for a channel.
        fn set_compare_value(&mut self, channel: Channel, value: u32) {
-            Self::regs_gp32().ccr(channel.raw()).modify(|w| w.set_ccr(value));
+            Self::regs_gp32().ccr(channel.index()).modify(|w| w.set_ccr(value));
        }
+        /// Get capture value for a channel.
        fn get_capture_value(&mut self, channel: Channel) -> u32 {
-            Self::regs_gp32().ccr(channel.raw()).read().ccr()
+            Self::regs_gp32().ccr(channel.index()).read().ccr()
        }
+        /// Get max compare value. This depends on the timer frequency and the clock frequency from RCC.
        fn get_max_compare_value(&self) -> u32 {
            Self::regs_gp32().arr().read().arr()
        }
+        /// Get compare value for a channel.
        fn get_compare_value(&self, channel: Channel) -> u32 {
-            Self::regs_gp32().ccr(channel.raw()).read().ccr()
+            Self::regs_gp32().ccr(channel.index()).read().ccr()
        }
    }
 }
+/// Timer channel.
 #[derive(Clone, Copy)]
 pub enum Channel {
+    /// Channel 1.
    Ch1,
+    /// Channel 2.
    Ch2,
+    /// Channel 3.
    Ch3,
+    /// Channel 4.
    Ch4,
 }
 impl Channel {
-    pub fn raw(&self) -> usize {
+    /// Get the channel index (0..3)
+    pub fn index(&self) -> usize {
        match self {
            Channel::Ch1 => 0,
            Channel::Ch2 => 1,
@@ -292,17 +366,25 @@ impl Channel {
    }
 }
+/// Input capture mode.
 #[derive(Clone, Copy)]
 pub enum InputCaptureMode {
+    /// Rising edge only.
    Rising,
+    /// Falling edge only.
    Falling,
+    /// Both rising or falling edges.
    BothEdges,
 }
+/// Input TI selection.
 #[derive(Clone, Copy)]
 pub enum InputTISelection {
+    /// Normal
    Normal,
+    /// Alternate
    Alternate,
+    /// TRC
    TRC,
 }
@@ -316,6 +398,7 @@ impl From<InputTISelection> for stm32_metapac::timer::vals::CcmrInputCcs {
    }
 }
+/// Timer counting mode.
 #[repr(u8)]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
 pub enum CountingMode {
@@ -342,6 +425,7 @@ pub enum CountingMode {
 }
 impl CountingMode {
+    /// Return whether this mode is edge-aligned (up or down).
    pub fn is_edge_aligned(&self) -> bool {
        match self {
            CountingMode::EdgeAlignedUp | CountingMode::EdgeAlignedDown => true,
@@ -349,6 +433,7 @@ impl CountingMode {
        }
    }
+    /// Return whether this mode is center-aligned.
    pub fn is_center_aligned(&self) -> bool {
        match self {
            CountingMode::CenterAlignedDownInterrupts
@@ -383,16 +468,34 @@ impl From<(vals::Cms, vals::Dir)> for CountingMode {
    }
 }
+/// Output compare mode.
 #[derive(Clone, Copy)]
 pub enum OutputCompareMode {
+    /// The comparison between the output compare register TIMx_CCRx and
+    /// the counter TIMx_CNT has no effect on the outputs.
+    /// (this mode is used to generate a timing base).
    Frozen,
+    /// Set channel to active level on match. OCxREF signal is forced high when the
+    /// counter TIMx_CNT matches the capture/compare register x (TIMx_CCRx).
    ActiveOnMatch,
+    /// Set channel to inactive level on match. OCxREF signal is forced low when the
+    /// counter TIMx_CNT matches the capture/compare register x (TIMx_CCRx).
    InactiveOnMatch,
+    /// Toggle - OCxREF toggles when TIMx_CNT=TIMx_CCRx.
    Toggle,
+    /// Force inactive level - OCxREF is forced low.
    ForceInactive,
+    /// Force active level - OCxREF is forced high.
    ForceActive,
+    /// PWM mode 1 - In upcounting, channel is active as long as TIMx_CNT<TIMx_CCRx
+    /// else inactive. In downcounting, channel is inactive (OCxREF=0) as long as
+    /// TIMx_CNT>TIMx_CCRx else active (OCxREF=1).
    PwmMode1,
+    /// PWM mode 2 - In upcounting, channel is inactive as long as
+    /// TIMx_CNT<TIMx_CCRx else active. In downcounting, channel is active as long as
+    /// TIMx_CNT>TIMx_CCRx else inactive.
    PwmMode2,
+    // TODO: there's more modes here depending on the chip family.
 }
 impl From<OutputCompareMode> for stm32_metapac::timer::vals::Ocm {
@@ -410,9 +513,12 @@ impl From<OutputCompareMode> for stm32_metapac::timer::vals::Ocm {
    }
 }
+/// Timer output pin polarity.
 #[derive(Clone, Copy)]
 pub enum OutputPolarity {
+    /// Active high (higher duty value makes the pin spend more time high).
    ActiveHigh,
+    /// Active low (higher duty value makes the pin spend more time low).
    ActiveLow,
 }
@@ -425,24 +531,31 @@ impl From<OutputPolarity> for bool {
    }
 }
+/// Basic 16-bit timer instance.
 pub trait Basic16bitInstance: sealed::Basic16bitInstance + 'static {}
+/// Gneral-purpose 16-bit timer instance.
 pub trait GeneralPurpose16bitInstance: sealed::GeneralPurpose16bitInstance + 'static {}
+/// Gneral-purpose 32-bit timer instance.
 pub trait GeneralPurpose32bitInstance: sealed::GeneralPurpose32bitInstance + 'static {}
+/// Advanced control timer instance.
 pub trait AdvancedControlInstance: sealed::AdvancedControlInstance + 'static {}
+/// Capture/Compare 16-bit timer instance.
 pub trait CaptureCompare16bitInstance:
    sealed::CaptureCompare16bitInstance + GeneralPurpose16bitInstance + 'static
 {
 }
+/// Capture/Compare 16-bit timer instance with complementary pin support.
 pub trait ComplementaryCaptureCompare16bitInstance:
    sealed::ComplementaryCaptureCompare16bitInstance + AdvancedControlInstance + 'static
 {
 }
+/// Capture/Compare 32-bit timer instance.
 pub trait CaptureCompare32bitInstance:
    sealed::CaptureCompare32bitInstance + CaptureCompare16bitInstance + GeneralPurpose32bitInstance + 'static
 {
diff --git a/embassy-stm32/src/timer/qei.rs b/embassy-stm32/src/timer/qei.rs
index 01d028bf9..59efb72ba 100644
--- a/embassy-stm32/src/timer/qei.rs
+++ b/embassy-stm32/src/timer/qei.rs
@@ -1,3 +1,5 @@
+//! Quadrature decoder using a timer.
 use core::marker::PhantomData;
 use embassy_hal_internal::{into_ref, PeripheralRef};
@@ -7,23 +9,30 @@ use crate::gpio::sealed::AFType;
 use crate::gpio::AnyPin;
 use crate::Peripheral;
+/// Counting direction
 pub enum Direction {
+    /// Counting up.
    Upcounting,
+    /// Counting down.
    Downcounting,
 }
-pub struct Ch1;
+/// Channel 1 marker type.
-pub struct Ch2;
+pub enum Ch1 {}
+/// Channel 2 marker type.
+pub enum Ch2 {}
-pub struct QeiPin<'d, Perip, Channel> {
+/// Wrapper for using a pin with QEI.
+pub struct QeiPin<'d, T, Channel> {
    _pin: PeripheralRef<'d, AnyPin>,
-    phantom: PhantomData<(Perip, Channel)>,
+    phantom: PhantomData<(T, Channel)>,
 }
 macro_rules! channel_impl {
    ($new_chx:ident, $channel:ident, $pin_trait:ident) => {
-        impl<'d, Perip: CaptureCompare16bitInstance> QeiPin<'d, Perip, $channel> {
+        impl<'d, T: CaptureCompare16bitInstance> QeiPin<'d, T, $channel> {
-            pub fn $new_chx(pin: impl Peripheral<P = impl $pin_trait<Perip>> + 'd) -> Self {
+            #[doc = concat!("Create a new ", stringify!($channel), " QEI pin instance.")]
+            pub fn $new_chx(pin: impl Peripheral<P = impl $pin_trait<T>> + 'd) -> Self {
                into_ref!(pin);
                critical_section::with(|_| {
                    pin.set_low();
@@ -43,11 +52,13 @@ macro_rules! channel_impl {
 channel_impl!(new_ch1, Ch1, Channel1Pin);
 channel_impl!(new_ch2, Ch2, Channel2Pin);
+/// Quadrature decoder driver.
 pub struct Qei<'d, T> {
    _inner: PeripheralRef<'d, T>,
 }
 impl<'d, T: CaptureCompare16bitInstance> Qei<'d, T> {
+    /// Create a new quadrature decoder driver.
    pub fn new(tim: impl Peripheral<P = T> + 'd, _ch1: QeiPin<'d, T, Ch1>, _ch2: QeiPin<'d, T, Ch2>) -> Self {
        Self::new_inner(tim)
    }
@@ -82,6 +93,7 @@ impl<'d, T: CaptureCompare16bitInstance> Qei<'d, T> {
        Self { _inner: tim }
    }
+    /// Get direction.
    pub fn read_direction(&self) -> Direction {
        match T::regs_gp16().cr1().read().dir() {
            vals::Dir::DOWN => Direction::Downcounting,
@@ -89,6 +101,7 @@ impl<'d, T: CaptureCompare16bitInstance> Qei<'d, T> {
        }
    }
+    /// Get count.
    pub fn count(&self) -> u16 {
        T::regs_gp16().cnt().read().cnt()
    }
diff --git a/embassy-stm32/src/timer/simple_pwm.rs b/embassy-stm32/src/timer/simple_pwm.rs
index 1cf0ad728..e6072aa15 100644
--- a/embassy-stm32/src/timer/simple_pwm.rs
+++ b/embassy-stm32/src/timer/simple_pwm.rs
@@ -1,3 +1,5 @@
+//! Simple PWM driver.
 use core::marker::PhantomData;
 use embassy_hal_internal::{into_ref, PeripheralRef};
@@ -9,20 +11,28 @@ use crate::gpio::{AnyPin, OutputType};
 use crate::time::Hertz;
 use crate::Peripheral;
-pub struct Ch1;
+/// Channel 1 marker type.
-pub struct Ch2;
+pub enum Ch1 {}
-pub struct Ch3;
+/// Channel 2 marker type.
-pub struct Ch4;
+pub enum Ch2 {}
+/// Channel 3 marker type.
-pub struct PwmPin<'d, Perip, Channel> {
+pub enum Ch3 {}
+/// Channel 4 marker type.
+pub enum Ch4 {}
+/// PWM pin wrapper.
+///
+/// This wraps a pin to make it usable with PWM.
+pub struct PwmPin<'d, T, C> {
    _pin: PeripheralRef<'d, AnyPin>,
-    phantom: PhantomData<(Perip, Channel)>,
+    phantom: PhantomData<(T, C)>,
 }
 macro_rules! channel_impl {
    ($new_chx:ident, $channel:ident, $pin_trait:ident) => {
-        impl<'d, Perip: CaptureCompare16bitInstance> PwmPin<'d, Perip, $channel> {
+        impl<'d, T: CaptureCompare16bitInstance> PwmPin<'d, T, $channel> {
-            pub fn $new_chx(pin: impl Peripheral<P = impl $pin_trait<Perip>> + 'd, output_type: OutputType) -> Self {
+            #[doc = concat!("Create a new ", stringify!($channel), " PWM pin instance.")]
+            pub fn $new_chx(pin: impl Peripheral<P = impl $pin_trait<T>> + 'd, output_type: OutputType) -> Self {
                into_ref!(pin);
                critical_section::with(|_| {
                    pin.set_low();
@@ -44,11 +54,13 @@ channel_impl!(new_ch2, Ch2, Channel2Pin);
 channel_impl!(new_ch3, Ch3, Channel3Pin);
 channel_impl!(new_ch4, Ch4, Channel4Pin);
+/// Simple PWM driver.
 pub struct SimplePwm<'d, T> {
    inner: PeripheralRef<'d, T>,
 }
 impl<'d, T: CaptureCompare16bitInstance> SimplePwm<'d, T> {
+    /// Create a new simple PWM driver.
    pub fn new(
        tim: impl Peripheral<P = T> + 'd,
        _ch1: Option<PwmPin<'d, T, Ch1>>,
@@ -69,7 +81,7 @@ impl<'d, T: CaptureCompare16bitInstance> SimplePwm<'d, T> {
        let mut this = Self { inner: tim };
        this.inner.set_counting_mode(counting_mode);
-        this.set_freq(freq);
+        this.set_frequency(freq);
        this.inner.start();
        this.inner.enable_outputs();
@@ -85,15 +97,21 @@ impl<'d, T: CaptureCompare16bitInstance> SimplePwm<'d, T> {
        this
    }
+    /// Enable the given channel.
    pub fn enable(&mut self, channel: Channel) {
        self.inner.enable_channel(channel, true);
    }
+    /// Disable the given channel.
    pub fn disable(&mut self, channel: Channel) {
        self.inner.enable_channel(channel, false);
    }
-    pub fn set_freq(&mut self, freq: Hertz) {
+    /// Set PWM frequency.
+    ///
+    /// Note: when you call this, the max duty value changes, so you will have to
+    /// call `set_duty` on all channels with the duty calculated based on the new max duty.
+    pub fn set_frequency(&mut self, freq: Hertz) {
        let multiplier = if self.inner.get_counting_mode().is_center_aligned() {
            2u8
        } else {
@@ -102,15 +120,22 @@ impl<'d, T: CaptureCompare16bitInstance> SimplePwm<'d, T> {
        self.inner.set_frequency(freq * multiplier);
    }
+    /// Get max duty value.
+    ///
+    /// This value depends on the configured frequency and the timer's clock rate from RCC.
    pub fn get_max_duty(&self) -> u16 {
        self.inner.get_max_compare_value() + 1
    }
+    /// Set the duty for a given channel.
+    ///
+    /// The value ranges from 0 for 0% duty, to [`get_max_duty`](Self::get_max_duty) for 100% duty, both included.
    pub fn set_duty(&mut self, channel: Channel, duty: u16) {
        assert!(duty <= self.get_max_duty());
        self.inner.set_compare_value(channel, duty)
    }
+    /// Set the output polarity for a given channel.
    pub fn set_polarity(&mut self, channel: Channel, polarity: OutputPolarity) {
        self.inner.set_output_polarity(channel, polarity);
    }
diff --git a/embassy-stm32/src/traits.rs b/embassy-stm32/src/traits.rs
index ffce7bd42..13f695821 100644
--- a/embassy-stm32/src/traits.rs
+++ b/embassy-stm32/src/traits.rs
@@ -1,16 +1,18 @@
 #![macro_use]
 macro_rules! pin_trait {
-    ($signal:ident, $instance:path) => {
+    ($signal:ident, $instance:path $(, $mode:path)?) => {
-        pub trait $signal<T: $instance>: crate::gpio::Pin {
+        #[doc = concat!(stringify!($signal), " pin trait")]
+        pub trait $signal<T: $instance $(, M: $mode)?>: crate::gpio::Pin {
+            #[doc = concat!("Get the AF number needed to use this pin as ", stringify!($signal))]
            fn af_num(&self) -> u8;
        }
    };
 }
 macro_rules! pin_trait_impl {
-    (crate::$mod:ident::$trait:ident, $instance:ident, $pin:ident, $af:expr) => {
+    (crate::$mod:ident::$trait:ident$(<$mode:ident>)?, $instance:ident, $pin:ident, $af:expr) => {
-        impl crate::$mod::$trait<crate::peripherals::$instance> for crate::peripherals::$pin {
+        impl crate::$mod::$trait<crate::peripherals::$instance $(, crate::$mod::$mode)?> for crate::peripherals::$pin {
            fn af_num(&self) -> u8 {
                $af
            }
@@ -21,8 +23,12 @@ macro_rules! pin_trait_impl {
 // ====================
 macro_rules! dma_trait {
-    ($signal:ident, $instance:path) => {
+    ($signal:ident, $instance:path$(, $mode:path)?) => {
-        pub trait $signal<T: $instance>: crate::dma::Channel {
+        #[doc = concat!(stringify!($signal), " DMA request trait")]
+        pub trait $signal<T: $instance $(, M: $mode)?>: crate::dma::Channel {
+            #[doc = concat!("Get the DMA request number needed to use this channel as", stringify!($signal))]
+            /// Note: in some chips, ST calls this the "channel", and calls channels "streams".
+            /// `embassy-stm32` always uses the "channel" and "request number" names.
            fn request(&self) -> crate::dma::Request;
        }
    };
@@ -31,8 +37,8 @@ macro_rules! dma_trait {
 #[allow(unused)]
 macro_rules! dma_trait_impl {
    // DMAMUX
-    (crate::$mod:ident::$trait:ident, $instance:ident, {dmamux: $dmamux:ident}, $request:expr) => {
+    (crate::$mod:ident::$trait:ident$(<$mode:ident>)?, $instance:ident, {dmamux: $dmamux:ident}, $request:expr) => {
-        impl<T> crate::$mod::$trait<crate::peripherals::$instance> for T
+        impl<T> crate::$mod::$trait<crate::peripherals::$instance $(, crate::$mod::$mode)?> for T
        where
            T: crate::dma::Channel + crate::dma::MuxChannel<Mux = crate::dma::$dmamux>,
        {
@@ -43,8 +49,8 @@ macro_rules! dma_trait_impl {
    };
    // DMAMUX
-    (crate::$mod:ident::$trait:ident, $instance:ident, {dma: $dma:ident}, $request:expr) => {
+    (crate::$mod:ident::$trait:ident$(<$mode:ident>)?, $instance:ident, {dma: $dma:ident}, $request:expr) => {
-        impl<T> crate::$mod::$trait<crate::peripherals::$instance> for T
+        impl<T> crate::$mod::$trait<crate::peripherals::$instance $(, crate::$mod::$mode)?> for T
        where
            T: crate::dma::Channel,
        {
@@ -55,8 +61,8 @@ macro_rules! dma_trait_impl {
    };
    // DMA/GPDMA, without DMAMUX
-    (crate::$mod:ident::$trait:ident, $instance:ident, {channel: $channel:ident}, $request:expr) => {
+    (crate::$mod:ident::$trait:ident$(<$mode:ident>)?, $instance:ident, {channel: $channel:ident}, $request:expr) => {
-        impl crate::$mod::$trait<crate::peripherals::$instance> for crate::peripherals::$channel {
+        impl crate::$mod::$trait<crate::peripherals::$instance $(, crate::$mod::$mode)?> for crate::peripherals::$channel {
            fn request(&self) -> crate::dma::Request {
                $request
            }
diff --git a/embassy-stm32/src/uid.rs b/embassy-stm32/src/uid.rs
index 6dcfcb96e..aa13586f8 100644
--- a/embassy-stm32/src/uid.rs
+++ b/embassy-stm32/src/uid.rs
@@ -1,3 +1,5 @@
+//! Unique ID (UID)
 /// Get this device's unique 96-bit ID.
 pub fn uid() -> &'static [u8; 12] {
    unsafe { &*crate::pac::UID.uid(0).as_ptr().cast::<[u8; 12]>() }
diff --git a/embassy-stm32/src/usart/buffered.rs b/embassy-stm32/src/usart/buffered.rs
index a2e4ceaae..962547bd7 100644
--- a/embassy-stm32/src/usart/buffered.rs
+++ b/embassy-stm32/src/usart/buffered.rs
@@ -82,6 +82,7 @@ impl<T: BasicInstance> interrupt::typelevel::Handler<T::Interrupt> for Interrupt
    }
 }
+/// Buffered UART State
 pub struct State {
    rx_waker: AtomicWaker,
    rx_buf: RingBuffer,
@@ -91,6 +92,7 @@ pub struct State {
 }
 impl State {
+    /// Create new state
    pub const fn new() -> Self {
        Self {
            rx_buf: RingBuffer::new(),
@@ -101,15 +103,18 @@ impl State {
    }
 }
+/// Bidirectional buffered UART
 pub struct BufferedUart<'d, T: BasicInstance> {
    rx: BufferedUartRx<'d, T>,
    tx: BufferedUartTx<'d, T>,
 }
+/// Tx-only buffered UART
 pub struct BufferedUartTx<'d, T: BasicInstance> {
    phantom: PhantomData<&'d mut T>,
 }
+/// Rx-only buffered UART
 pub struct BufferedUartRx<'d, T: BasicInstance> {
    phantom: PhantomData<&'d mut T>,
 }
@@ -142,6 +147,7 @@ impl<'d, T: BasicInstance> SetConfig for BufferedUartTx<'d, T> {
 }
 impl<'d, T: BasicInstance> BufferedUart<'d, T> {
+    /// Create a new bidirectional buffered UART driver
    pub fn new(
        peri: impl Peripheral<P = T> + 'd,
        _irq: impl interrupt::typelevel::Binding<T::Interrupt, InterruptHandler<T>> + 'd,
@@ -158,6 +164,7 @@ impl<'d, T: BasicInstance> BufferedUart<'d, T> {
        Self::new_inner(peri, rx, tx, tx_buffer, rx_buffer, config)
    }
+    /// Create a new bidirectional buffered UART driver with request-to-send and clear-to-send pins
    pub fn new_with_rtscts(
        peri: impl Peripheral<P = T> + 'd,
        _irq: impl interrupt::typelevel::Binding<T::Interrupt, InterruptHandler<T>> + 'd,
@@ -185,6 +192,7 @@ impl<'d, T: BasicInstance> BufferedUart<'d, T> {
        Self::new_inner(peri, rx, tx, tx_buffer, rx_buffer, config)
    }
+    /// Create a new bidirectional buffered UART driver with a driver-enable pin
    #[cfg(not(any(usart_v1, usart_v2)))]
    pub fn new_with_de(
        peri: impl Peripheral<P = T> + 'd,
@@ -246,10 +254,12 @@ impl<'d, T: BasicInstance> BufferedUart<'d, T> {
        })
    }
+    /// Split the driver into a Tx and Rx part (useful for sending to separate tasks)
    pub fn split(self) -> (BufferedUartTx<'d, T>, BufferedUartRx<'d, T>) {
        (self.tx, self.rx)
    }
+    /// Reconfigure the driver
    pub fn set_config(&mut self, config: &Config) -> Result<(), ConfigError> {
        reconfigure::<T>(config)?;
@@ -337,6 +347,7 @@ impl<'d, T: BasicInstance> BufferedUartRx<'d, T> {
        }
    }
+    /// Reconfigure the driver
    pub fn set_config(&mut self, config: &Config) -> Result<(), ConfigError> {
        reconfigure::<T>(config)?;
@@ -418,6 +429,7 @@ impl<'d, T: BasicInstance> BufferedUartTx<'d, T> {
        }
    }
+    /// Reconfigure the driver
    pub fn set_config(&mut self, config: &Config) -> Result<(), ConfigError> {
        reconfigure::<T>(config)?;
diff --git a/embassy-stm32/src/usart/mod.rs b/embassy-stm32/src/usart/mod.rs
index d5828a492..8a0c85d2c 100644
--- a/embassy-stm32/src/usart/mod.rs
+++ b/embassy-stm32/src/usart/mod.rs
@@ -1,4 +1,6 @@
+//! Universal Synchronous/Asynchronous Receiver Transmitter (USART, UART, LPUART)
 #![macro_use]
+#![warn(missing_docs)]
 use core::future::poll_fn;
 use core::marker::PhantomData;
@@ -76,21 +78,29 @@ impl<T: BasicInstance> interrupt::typelevel::Handler<T::Interrupt> for Interrupt
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
+/// Number of data bits
 pub enum DataBits {
+    /// 8 Data Bits
    DataBits8,
+    /// 9 Data Bits
    DataBits9,
 }
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
+/// Parity
 pub enum Parity {
+    /// No parity
    ParityNone,
+    /// Even Parity
    ParityEven,
+    /// Odd Parity
    ParityOdd,
 }
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
+/// Number of stop bits
 pub enum StopBits {
    #[doc = "1 stop bit"]
    STOP1,
@@ -105,26 +115,37 @@ pub enum StopBits {
 #[non_exhaustive]
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
+/// Config Error
 pub enum ConfigError {
+    /// Baudrate too low
    BaudrateTooLow,
+    /// Baudrate too high
    BaudrateTooHigh,
+    /// Rx or Tx not enabled
    RxOrTxNotEnabled,
 }
 #[non_exhaustive]
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
+/// Config
 pub struct Config {
+    /// Baud rate
    pub baudrate: u32,
+    /// Number of data bits
    pub data_bits: DataBits,
+    /// Number of stop bits
    pub stop_bits: StopBits,
+    /// Parity type
    pub parity: Parity,
-    /// if true, on read-like method, if there is a latent error pending,
-    /// read will abort, the error reported and cleared
+    /// If true: on a read-like method, if there is a latent error pending,
-    /// if false, the error is ignored and cleared
+    /// the read will abort and the error will be reported and cleared
+    ///
+    /// If false: the error is ignored and cleared
    pub detect_previous_overrun: bool,
    /// Set this to true if the line is considered noise free.
-    /// This will increase the receivers tolerance to clock deviations,
+    /// This will increase the receiver’s tolerance to clock deviations,
    /// but will effectively disable noise detection.
    #[cfg(not(usart_v1))]
    pub assume_noise_free: bool,
@@ -132,6 +153,14 @@ pub struct Config {
    /// Set this to true to swap the RX and TX pins.
    #[cfg(any(usart_v3, usart_v4))]
    pub swap_rx_tx: bool,
+    /// Set this to true to invert TX pin signal values (V<sub>DD</sub> =0/mark, Gnd = 1/idle).
+    #[cfg(any(usart_v3, usart_v4))]
+    pub invert_tx: bool,
+    /// Set this to true to invert RX pin signal values (V<sub>DD</sub> =0/mark, Gnd = 1/idle).
+    #[cfg(any(usart_v3, usart_v4))]
+    pub invert_rx: bool,
 }
 impl Default for Config {
@@ -147,6 +176,10 @@ impl Default for Config {
            assume_noise_free: false,
            #[cfg(any(usart_v3, usart_v4))]
            swap_rx_tx: false,
+            #[cfg(any(usart_v3, usart_v4))]
+            invert_tx: false,
+            #[cfg(any(usart_v3, usart_v4))]
+            invert_rx: false,
        }
    }
 }
@@ -175,6 +208,7 @@ enum ReadCompletionEvent {
    Idle(usize),
 }
+/// Bidirectional UART Driver
 pub struct Uart<'d, T: BasicInstance, TxDma = NoDma, RxDma = NoDma> {
    tx: UartTx<'d, T, TxDma>,
    rx: UartRx<'d, T, RxDma>,
@@ -190,6 +224,7 @@ impl<'d, T: BasicInstance, TxDma, RxDma> SetConfig for Uart<'d, T, TxDma, RxDma>
    }
 }
+/// Tx-only UART Driver
 pub struct UartTx<'d, T: BasicInstance, TxDma = NoDma> {
    phantom: PhantomData<&'d mut T>,
    tx_dma: PeripheralRef<'d, TxDma>,
@@ -204,6 +239,7 @@ impl<'d, T: BasicInstance, TxDma> SetConfig for UartTx<'d, T, TxDma> {
    }
 }
+/// Rx-only UART Driver
 pub struct UartRx<'d, T: BasicInstance, RxDma = NoDma> {
    _peri: PeripheralRef<'d, T>,
    rx_dma: PeripheralRef<'d, RxDma>,
@@ -234,6 +270,7 @@ impl<'d, T: BasicInstance, TxDma> UartTx<'d, T, TxDma> {
        Self::new_inner(peri, tx, tx_dma, config)
    }
+    /// Create a new tx-only UART with a clear-to-send pin
    pub fn new_with_cts(
        peri: impl Peripheral<P = T> + 'd,
        tx: impl Peripheral<P = impl TxPin<T>> + 'd,
@@ -275,10 +312,12 @@ impl<'d, T: BasicInstance, TxDma> UartTx<'d, T, TxDma> {
        })
    }
+    /// Reconfigure the driver
    pub fn set_config(&mut self, config: &Config) -> Result<(), ConfigError> {
        reconfigure::<T>(config)
    }
+    /// Initiate an asynchronous UART write
    pub async fn write(&mut self, buffer: &[u8]) -> Result<(), Error>
    where
        TxDma: crate::usart::TxDma<T>,
@@ -295,6 +334,7 @@ impl<'d, T: BasicInstance, TxDma> UartTx<'d, T, TxDma> {
        Ok(())
    }
+    /// Perform a blocking UART write
    pub fn blocking_write(&mut self, buffer: &[u8]) -> Result<(), Error> {
        let r = T::regs();
        for &b in buffer {
@@ -304,6 +344,7 @@ impl<'d, T: BasicInstance, TxDma> UartTx<'d, T, TxDma> {
        Ok(())
    }
+    /// Block until transmission complete
    pub fn blocking_flush(&mut self) -> Result<(), Error> {
        let r = T::regs();
        while !sr(r).read().tc() {}
@@ -325,6 +366,7 @@ impl<'d, T: BasicInstance, RxDma> UartRx<'d, T, RxDma> {
        Self::new_inner(peri, rx, rx_dma, config)
    }
+    /// Create a new rx-only UART with a request-to-send pin
    pub fn new_with_rts(
        peri: impl Peripheral<P = T> + 'd,
        _irq: impl interrupt::typelevel::Binding<T::Interrupt, InterruptHandler<T>> + 'd,
@@ -374,6 +416,7 @@ impl<'d, T: BasicInstance, RxDma> UartRx<'d, T, RxDma> {
        })
    }
+    /// Reconfigure the driver
    pub fn set_config(&mut self, config: &Config) -> Result<(), ConfigError> {
        reconfigure::<T>(config)
    }
@@ -431,6 +474,7 @@ impl<'d, T: BasicInstance, RxDma> UartRx<'d, T, RxDma> {
        Ok(sr.rxne())
    }
+    /// Initiate an asynchronous UART read
    pub async fn read(&mut self, buffer: &mut [u8]) -> Result<(), Error>
    where
        RxDma: crate::usart::RxDma<T>,
@@ -440,6 +484,7 @@ impl<'d, T: BasicInstance, RxDma> UartRx<'d, T, RxDma> {
        Ok(())
    }
+    /// Read a single u8 if there is one available, otherwise return WouldBlock
    pub fn nb_read(&mut self) -> Result<u8, nb::Error<Error>> {
        let r = T::regs();
        if self.check_rx_flags()? {
@@ -449,6 +494,7 @@ impl<'d, T: BasicInstance, RxDma> UartRx<'d, T, RxDma> {
        }
    }
+    /// Perform a blocking read into `buffer`
    pub fn blocking_read(&mut self, buffer: &mut [u8]) -> Result<(), Error> {
        let r = T::regs();
        for b in buffer {
@@ -458,6 +504,7 @@ impl<'d, T: BasicInstance, RxDma> UartRx<'d, T, RxDma> {
        Ok(())
    }
+    /// Initiate an asynchronous read with idle line detection enabled
    pub async fn read_until_idle(&mut self, buffer: &mut [u8]) -> Result<usize, Error>
    where
        RxDma: crate::usart::RxDma<T>,
@@ -682,6 +729,7 @@ impl<'d, T: BasicInstance, TxDma> Drop for UartRx<'d, T, TxDma> {
 }
 impl<'d, T: BasicInstance, TxDma, RxDma> Uart<'d, T, TxDma, RxDma> {
+    /// Create a new bidirectional UART
    pub fn new(
        peri: impl Peripheral<P = T> + 'd,
        rx: impl Peripheral<P = impl RxPin<T>> + 'd,
@@ -698,6 +746,7 @@ impl<'d, T: BasicInstance, TxDma, RxDma> Uart<'d, T, TxDma, RxDma> {
        Self::new_inner(peri, rx, tx, tx_dma, rx_dma, config)
    }
+    /// Create a new bidirectional UART with request-to-send and clear-to-send pins
    pub fn new_with_rtscts(
        peri: impl Peripheral<P = T> + 'd,
        rx: impl Peripheral<P = impl RxPin<T>> + 'd,
@@ -725,6 +774,7 @@ impl<'d, T: BasicInstance, TxDma, RxDma> Uart<'d, T, TxDma, RxDma> {
    }
    #[cfg(not(any(usart_v1, usart_v2)))]
+    /// Create a new bidirectional UART with a driver-enable pin
    pub fn new_with_de(
        peri: impl Peripheral<P = T> + 'd,
        rx: impl Peripheral<P = impl RxPin<T>> + 'd,
@@ -800,6 +850,7 @@ impl<'d, T: BasicInstance, TxDma, RxDma> Uart<'d, T, TxDma, RxDma> {
        })
    }
+    /// Initiate an asynchronous write
    pub async fn write(&mut self, buffer: &[u8]) -> Result<(), Error>
    where
        TxDma: crate::usart::TxDma<T>,
@@ -807,14 +858,17 @@ impl<'d, T: BasicInstance, TxDma, RxDma> Uart<'d, T, TxDma, RxDma> {
        self.tx.write(buffer).await
    }
+    /// Perform a blocking write
    pub fn blocking_write(&mut self, buffer: &[u8]) -> Result<(), Error> {
        self.tx.blocking_write(buffer)
    }
+    /// Block until transmission complete
    pub fn blocking_flush(&mut self) -> Result<(), Error> {
        self.tx.blocking_flush()
    }
+    /// Initiate an asynchronous read into `buffer`
    pub async fn read(&mut self, buffer: &mut [u8]) -> Result<(), Error>
    where
        RxDma: crate::usart::RxDma<T>,
@@ -822,14 +876,17 @@ impl<'d, T: BasicInstance, TxDma, RxDma> Uart<'d, T, TxDma, RxDma> {
        self.rx.read(buffer).await
    }
+    /// Read a single `u8` or return `WouldBlock`
    pub fn nb_read(&mut self) -> Result<u8, nb::Error<Error>> {
        self.rx.nb_read()
    }
+    /// Perform a blocking read into `buffer`
    pub fn blocking_read(&mut self, buffer: &mut [u8]) -> Result<(), Error> {
        self.rx.blocking_read(buffer)
    }
+    /// Initiate an an asynchronous read with idle line detection enabled
    pub async fn read_until_idle(&mut self, buffer: &mut [u8]) -> Result<usize, Error>
    where
        RxDma: crate::usart::RxDma<T>,
@@ -972,7 +1029,11 @@ fn configure(
        });
        #[cfg(any(usart_v3, usart_v4))]
-        w.set_swap(config.swap_rx_tx);
+        {
+            w.set_txinv(config.invert_tx);
+            w.set_rxinv(config.invert_rx);
+            w.set_swap(config.swap_rx_tx);
+        }
    });
    #[cfg(not(usart_v1))]
@@ -1275,8 +1336,10 @@ pub(crate) mod sealed {
    }
 }
+/// Basic UART driver instance
 pub trait BasicInstance: Peripheral<P = Self> + sealed::BasicInstance + 'static + Send {}
+/// Full UART driver instance
 pub trait FullInstance: sealed::FullInstance {}
 pin_trait!(RxPin, BasicInstance);
diff --git a/embassy-stm32/src/usart/ringbuffered.rs b/embassy-stm32/src/usart/ringbuffered.rs
index b8d17e4e4..4391bfef7 100644
--- a/embassy-stm32/src/usart/ringbuffered.rs
+++ b/embassy-stm32/src/usart/ringbuffered.rs
@@ -11,6 +11,7 @@ use super::{clear_interrupt_flags, rdr, reconfigure, sr, BasicInstance, Config,
 use crate::dma::ReadableRingBuffer;
 use crate::usart::{Regs, Sr};
+/// Rx-only Ring-buffered UART Driver
 pub struct RingBufferedUartRx<'d, T: BasicInstance, RxDma: super::RxDma<T>> {
    _peri: PeripheralRef<'d, T>,
    ring_buf: ReadableRingBuffer<'d, RxDma, u8>,
@@ -27,8 +28,8 @@ impl<'d, T: BasicInstance, RxDma: super::RxDma<T>> SetConfig for RingBufferedUar
 impl<'d, T: BasicInstance, RxDma: super::RxDma<T>> UartRx<'d, T, RxDma> {
    /// Turn the `UartRx` into a buffered uart which can continously receive in the background
-    /// without the possibility of loosing bytes. The `dma_buf` is a buffer registered to the
+    /// without the possibility of losing bytes. The `dma_buf` is a buffer registered to the
-    /// DMA controller, and must be sufficiently large, such that it will not overflow.
+    /// DMA controller, and must be large enough to prevent overflows.
    pub fn into_ring_buffered(self, dma_buf: &'d mut [u8]) -> RingBufferedUartRx<'d, T, RxDma> {
        assert!(!dma_buf.is_empty() && dma_buf.len() <= 0xFFFF);
@@ -39,7 +40,7 @@ impl<'d, T: BasicInstance, RxDma: super::RxDma<T>> UartRx<'d, T, RxDma> {
        let rx_dma = unsafe { self.rx_dma.clone_unchecked() };
        let _peri = unsafe { self._peri.clone_unchecked() };
-        let ring_buf = unsafe { ReadableRingBuffer::new_read(rx_dma, request, rdr(T::regs()), dma_buf, opts) };
+        let ring_buf = unsafe { ReadableRingBuffer::new(rx_dma, request, rdr(T::regs()), dma_buf, opts) };
        // Don't disable the clock
        mem::forget(self);
@@ -49,6 +50,7 @@ impl<'d, T: BasicInstance, RxDma: super::RxDma<T>> UartRx<'d, T, RxDma> {
 }
 impl<'d, T: BasicInstance, RxDma: super::RxDma<T>> RingBufferedUartRx<'d, T, RxDma> {
+    /// Clear the ring buffer and start receiving in the background
    pub fn start(&mut self) -> Result<(), Error> {
        // Clear the ring buffer so that it is ready to receive data
        self.ring_buf.clear();
@@ -64,6 +66,7 @@ impl<'d, T: BasicInstance, RxDma: super::RxDma<T>> RingBufferedUartRx<'d, T, RxD
        Err(err)
    }
+    /// Cleanly stop and reconfigure the driver
    pub fn set_config(&mut self, config: &Config) -> Result<(), ConfigError> {
        self.teardown_uart();
        reconfigure::<T>(config)
diff --git a/embassy-stm32/src/usb/mod.rs b/embassy-stm32/src/usb/mod.rs
index d0b289462..4debd4e54 100644
--- a/embassy-stm32/src/usb/mod.rs
+++ b/embassy-stm32/src/usb/mod.rs
@@ -1,3 +1,5 @@
+//! Universal Serial Bus (USB)
 use crate::interrupt;
 use crate::rcc::RccPeripheral;
@@ -10,7 +12,9 @@ pub(crate) mod sealed {
    }
 }
+/// USB instance trait.
 pub trait Instance: sealed::Instance + RccPeripheral + 'static {
+    /// Interrupt for this USB instance.
    type Interrupt: interrupt::typelevel::Interrupt;
 }
diff --git a/embassy-stm32/src/usb/usb.rs b/embassy-stm32/src/usb/usb.rs
index 295dc9198..04b1b35e8 100644
--- a/embassy-stm32/src/usb/usb.rs
+++ b/embassy-stm32/src/usb/usb.rs
@@ -244,6 +244,7 @@ struct EndpointData {
    used_out: bool,
 }
+/// USB driver.
 pub struct Driver<'d, T: Instance> {
    phantom: PhantomData<&'d mut T>,
    alloc: [EndpointData; EP_COUNT],
@@ -251,6 +252,7 @@ pub struct Driver<'d, T: Instance> {
 }
 impl<'d, T: Instance> Driver<'d, T> {
+    /// Create a new USB driver.
    pub fn new(
        _usb: impl Peripheral<P = T> + 'd,
        _irq: impl interrupt::typelevel::Binding<T::Interrupt, InterruptHandler<T>> + 'd,
@@ -465,6 +467,7 @@ impl<'d, T: Instance> driver::Driver<'d> for Driver<'d, T> {
    }
 }
+/// USB bus.
 pub struct Bus<'d, T: Instance> {
    phantom: PhantomData<&'d mut T>,
    ep_types: [EpType; EP_COUNT - 1],
@@ -640,6 +643,7 @@ trait Dir {
    fn waker(i: usize) -> &'static AtomicWaker;
 }
+/// Marker type for the "IN" direction.
 pub enum In {}
 impl Dir for In {
    fn dir() -> Direction {
@@ -652,6 +656,7 @@ impl Dir for In {
    }
 }
+/// Marker type for the "OUT" direction.
 pub enum Out {}
 impl Dir for Out {
    fn dir() -> Direction {
@@ -664,6 +669,7 @@ impl Dir for Out {
    }
 }
+/// USB endpoint.
 pub struct Endpoint<'d, T: Instance, D> {
    _phantom: PhantomData<(&'d mut T, D)>,
    info: EndpointInfo,
@@ -695,10 +701,10 @@ impl<'d, T: Instance> driver::Endpoint for Endpoint<'d, T, In> {
    }
    async fn wait_enabled(&mut self) {
-        trace!("wait_enabled OUT WAITING");
+        trace!("wait_enabled IN WAITING");
        let index = self.info.addr.index();
        poll_fn(|cx| {
-            EP_OUT_WAKERS[index].register(cx.waker());
+            EP_IN_WAKERS[index].register(cx.waker());
            let regs = T::regs();
            if regs.epr(index).read().stat_tx() == Stat::DISABLED {
                Poll::Pending
@@ -707,7 +713,7 @@ impl<'d, T: Instance> driver::Endpoint for Endpoint<'d, T, In> {
            }
        })
        .await;
-        trace!("wait_enabled OUT OK");
+        trace!("wait_enabled IN OK");
    }
 }
@@ -813,6 +819,7 @@ impl<'d, T: Instance> driver::EndpointIn for Endpoint<'d, T, In> {
    }
 }
+/// USB control pipe.
 pub struct ControlPipe<'d, T: Instance> {
    _phantom: PhantomData<&'d mut T>,
    max_packet_size: u16,
diff --git a/embassy-stm32/src/usb_otg/mod.rs b/embassy-stm32/src/usb_otg/mod.rs
index be54a3d10..0649e684b 100644
--- a/embassy-stm32/src/usb_otg/mod.rs
+++ b/embassy-stm32/src/usb_otg/mod.rs
@@ -1,3 +1,5 @@
+//! USB On The Go (OTG)
 use crate::rcc::RccPeripheral;
 use crate::{interrupt, peripherals};
@@ -18,7 +20,9 @@ pub(crate) mod sealed {
    }
 }
+/// USB OTG instance.
 pub trait Instance: sealed::Instance + RccPeripheral {
+    /// Interrupt for this USB OTG instance.
    type Interrupt: interrupt::typelevel::Interrupt;
 }
diff --git a/embassy-stm32/src/usb_otg/usb.rs b/embassy-stm32/src/usb_otg/usb.rs
index ba77bfb16..190fb274f 100644
--- a/embassy-stm32/src/usb_otg/usb.rs
+++ b/embassy-stm32/src/usb_otg/usb.rs
@@ -204,6 +204,7 @@ pub enum PhyType {
 }
 impl PhyType {
+    /// Get whether this PHY is any of the internal types.
    pub fn internal(&self) -> bool {
        match self {
            PhyType::InternalFullSpeed | PhyType::InternalHighSpeed => true,
@@ -211,6 +212,7 @@ impl PhyType {
        }
    }
+    /// Get whether this PHY is any of the high-speed types.
    pub fn high_speed(&self) -> bool {
        match self {
            PhyType::InternalFullSpeed => false,
@@ -218,7 +220,7 @@ impl PhyType {
        }
    }
-    pub fn to_dspd(&self) -> vals::Dspd {
+    fn to_dspd(&self) -> vals::Dspd {
        match self {
            PhyType::InternalFullSpeed => vals::Dspd::FULL_SPEED_INTERNAL,
            PhyType::InternalHighSpeed => vals::Dspd::HIGH_SPEED,
@@ -230,6 +232,7 @@ impl PhyType {
 /// Indicates that [State::ep_out_buffers] is empty.
 const EP_OUT_BUFFER_EMPTY: u16 = u16::MAX;
+/// USB OTG driver state.
 pub struct State<const EP_COUNT: usize> {
    /// Holds received SETUP packets. Available if [State::ep0_setup_ready] is true.
    ep0_setup_data: UnsafeCell<[u8; 8]>,
@@ -247,6 +250,7 @@ unsafe impl<const EP_COUNT: usize> Send for State<EP_COUNT> {}
 unsafe impl<const EP_COUNT: usize> Sync for State<EP_COUNT> {}
 impl<const EP_COUNT: usize> State<EP_COUNT> {
+    /// Create a new State.
    pub const fn new() -> Self {
        const NEW_AW: AtomicWaker = AtomicWaker::new();
        const NEW_BUF: UnsafeCell<*mut u8> = UnsafeCell::new(0 as _);
@@ -271,6 +275,7 @@ struct EndpointData {
    fifo_size_words: u16,
 }
+/// USB driver config.
 #[non_exhaustive]
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub struct Config {
@@ -297,6 +302,7 @@ impl Default for Config {
    }
 }
+/// USB driver.
 pub struct Driver<'d, T: Instance> {
    config: Config,
    phantom: PhantomData<&'d mut T>,
@@ -527,6 +533,7 @@ impl<'d, T: Instance> embassy_usb_driver::Driver<'d> for Driver<'d, T> {
    }
 }
+/// USB bus.
 pub struct Bus<'d, T: Instance> {
    config: Config,
    phantom: PhantomData<&'d mut T>,
@@ -1092,6 +1099,7 @@ trait Dir {
    fn dir() -> Direction;
 }
+/// Marker type for the "IN" direction.
 pub enum In {}
 impl Dir for In {
    fn dir() -> Direction {
@@ -1099,6 +1107,7 @@ impl Dir for In {
    }
 }
+/// Marker type for the "OUT" direction.
 pub enum Out {}
 impl Dir for Out {
    fn dir() -> Direction {
@@ -1106,6 +1115,7 @@ impl Dir for Out {
    }
 }
+/// USB endpoint.
 pub struct Endpoint<'d, T: Instance, D> {
    _phantom: PhantomData<(&'d mut T, D)>,
    info: EndpointInfo,
@@ -1299,6 +1309,7 @@ impl<'d, T: Instance> embassy_usb_driver::EndpointIn for Endpoint<'d, T, In> {
    }
 }
+/// USB control pipe.
 pub struct ControlPipe<'d, T: Instance> {
    _phantom: PhantomData<&'d mut T>,
    max_packet_size: u16,
diff --git a/embassy-stm32/src/wdg/mod.rs b/embassy-stm32/src/wdg/mod.rs
index c7c2694e0..dc701ef64 100644
--- a/embassy-stm32/src/wdg/mod.rs
+++ b/embassy-stm32/src/wdg/mod.rs
@@ -1,3 +1,4 @@
+//! Watchdog Timer (IWDG, WWDG)
 use core::marker::PhantomData;
 use embassy_hal_internal::{into_ref, Peripheral};
@@ -5,6 +6,7 @@ use stm32_metapac::iwdg::vals::{Key, Pr};
 use crate::rcc::LSI_FREQ;
+/// Independent watchdog (IWDG) driver.
 pub struct IndependentWatchdog<'d, T: Instance> {
    wdg: PhantomData<&'d mut T>,
 }
@@ -63,10 +65,12 @@ impl<'d, T: Instance> IndependentWatchdog<'d, T> {
        IndependentWatchdog { wdg: PhantomData }
    }
+    /// Unleash (start) the watchdog.
    pub fn unleash(&mut self) {
        T::regs().kr().write(|w| w.set_key(Key::START));
    }
+    /// Pet (reload, refresh) the watchdog.
    pub fn pet(&mut self) {
        T::regs().kr().write(|w| w.set_key(Key::RESET));
    }
@@ -78,6 +82,7 @@ mod sealed {
    }
 }
+/// IWDG instance trait.
 pub trait Instance: sealed::Instance {}
 foreach_peripheral!(
author	sodo <[email protected]>	2024-01-02 01:37:00 +0900
committer	sodo <[email protected]>	2024-01-02 13:34:22 +0900
commit	6ee153a3e2eec284c0d9d87f31801265c0604f74 (patch)
tree	8b801cbd15f9ad5052d5942c731e75736dc9d7eb /embassy-stm32/src
parent	b7cd7952c890f585ff876c622482534e5d58d4a4 (diff)
parent	0be9b0599aaf2e425d76ec7852ff4b3535defddf (diff)