docs: document spi, rtc and rest of uart for embassy-rp

stm32/sai: docs, cleanup api.

cyw43-pio/src/lib.rs

@@ -6,8 +6,8 @@ use core::slice;
 use cyw43::SpiBusCyw43;
 use embassy_rp::dma::Channel;
 use embassy_rp::gpio::{Drive, Level, Output, Pin, Pull, SlewRate};
-use embassy_rp::pio::{Common, Config, Direction, Instance, Irq, PioPin, ShiftDirection, StateMachine};
-use embassy_rp::{pio_instr_util, Peripheral, PeripheralRef};
+use embassy_rp::pio::{instr, Common, Config, Direction, Instance, Irq, PioPin, ShiftDirection, StateMachine};
+use embassy_rp::{Peripheral, PeripheralRef};
 use fixed::FixedU32;
 use pio_proc::pio_asm;
 
@@ -152,10 +152,10 @@ where
         defmt::trace!("write={} read={}", write_bits, read_bits);
 
         unsafe {
-            pio_instr_util::set_x(&mut self.sm, write_bits as u32);
-            pio_instr_util::set_y(&mut self.sm, read_bits as u32);
-            pio_instr_util::set_pindir(&mut self.sm, 0b1);
-            pio_instr_util::exec_jmp(&mut self.sm, self.wrap_target);
+            instr::set_x(&mut self.sm, write_bits as u32);
+            instr::set_y(&mut self.sm, read_bits as u32);
+            instr::set_pindir(&mut self.sm, 0b1);
+            instr::exec_jmp(&mut self.sm, self.wrap_target);
         }
 
         self.sm.set_enable(true);
@@ -179,10 +179,10 @@ where
         defmt::trace!("write={} read={}", write_bits, read_bits);
 
         unsafe {
-            pio_instr_util::set_y(&mut self.sm, read_bits as u32);
-            pio_instr_util::set_x(&mut self.sm, write_bits as u32);
-            pio_instr_util::set_pindir(&mut self.sm, 0b1);
-            pio_instr_util::exec_jmp(&mut self.sm, self.wrap_target);
+            instr::set_y(&mut self.sm, read_bits as u32);
+            instr::set_x(&mut self.sm, write_bits as u32);
+            instr::set_pindir(&mut self.sm, 0b1);
+            instr::exec_jmp(&mut self.sm, self.wrap_target);
         }
 
         // self.cs.set_low();

embassy-nrf/README.md

@@ -6,6 +6,8 @@ The Embassy nRF HAL targets the Nordic Semiconductor nRF family of hardware. The
 for many peripherals. The benefit of using the async APIs is that the HAL takes care of waiting for peripherals to
 complete operations in low power mod and handling interrupts, so that applications can focus on more important matters.
 
+NOTE: The Embassy HALs can be used both for non-async and async operations. For async, you can choose which runtime you want to use.
+
 ## EasyDMA considerations
 
 On nRF chips, peripherals can use the so called EasyDMA feature to offload the task of interacting

embassy-nrf/src/lib.rs

@@ -354,7 +354,11 @@ unsafe fn uicr_write_masked(address: *mut u32, value: u32, mask: u32) -> WriteRe
     WriteResult::Written
 }
 
-/// Initialize peripherals with the provided configuration. This should only be called once at startup.
+/// Initialize the `embassy-nrf` 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::Config) -> Peripherals {
     // Do this first, so that it panics if user is calling `init` a second time
     // before doing anything important.

embassy-rp/README.md

@@ -0,0 +1,23 @@
+# Embassy RP HAL
+
+HALs implement safe, idiomatic Rust APIs to use the hardware capabilities, so raw register manipulation is not needed.
+
+The Embassy RP HAL targets the Raspberry Pi 2040 family of hardware. The HAL implements both blocking and async APIs
+for many peripherals. The benefit of using the async APIs is that the HAL takes care of waiting for peripherals to
+complete operations in low power mod and handling interrupts, so that applications can focus on more important matters.
+
+NOTE: The Embassy HALs can be used both for non-async and async operations. For async, you can choose which runtime you want to use.
+
+## Minimum supported Rust version (MSRV)
+
+Embassy is guaranteed to compile on the latest stable Rust version at the time of release. It might compile with older versions but that may change in any new patch release.
+
+## License
+
+This work is licensed under either of
+
+- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
+  <http://www.apache.org/licenses/LICENSE-2.0>)
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
+
+at your option.

embassy-rp/src/clocks.rs

@@ -1,3 +1,4 @@
+//! Clock configuration for the RP2040
 use core::arch::asm;
 use core::marker::PhantomData;
 use core::sync::atomic::{AtomicU16, AtomicU32, Ordering};
@@ -44,6 +45,7 @@ static CLOCKS: Clocks = Clocks {
     rtc: AtomicU16::new(0),
 };
 
+/// Enumeration of supported clock sources.
 #[repr(u8)]
 #[non_exhaustive]
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
@@ -57,15 +59,24 @@ pub enum PeriClkSrc {
     // Gpin1 = ClkPeriCtrlAuxsrc::CLKSRC_GPIN1 as _ ,
 }
 
+/// CLock configuration.
 #[non_exhaustive]
 pub struct ClockConfig {
+    /// Ring oscillator configuration.
     pub rosc: Option<RoscConfig>,
+    /// External oscillator configuration.
     pub xosc: Option<XoscConfig>,
+    /// Reference clock configuration.
     pub ref_clk: RefClkConfig,
+    /// System clock configuration.
     pub sys_clk: SysClkConfig,
+    /// Peripheral clock source configuration.
     pub peri_clk_src: Option<PeriClkSrc>,
+    /// USB clock configuration.
     pub usb_clk: Option<UsbClkConfig>,
+    /// ADC clock configuration.
     pub adc_clk: Option<AdcClkConfig>,
+    /// RTC clock configuration.
     pub rtc_clk: Option<RtcClkConfig>,
     // gpin0: Option<(u32, Gpin<'static, AnyPin>)>,
     // gpin1: Option<(u32, Gpin<'static, AnyPin>)>,
@@ -189,31 +200,46 @@ pub enum RoscRange {
     TooHigh = pac::rosc::vals::FreqRange::TOOHIGH.0,
 }
 
+/// On-chip ring oscillator configuration.
 pub struct RoscConfig {
     /// Final frequency of the oscillator, after the divider has been applied.
     /// The oscillator has a nominal frequency of 6.5MHz at medium range with
     /// divider 16 and all drive strengths set to 0, other values should be
     /// measured in situ.
     pub hz: u32,
+    /// Oscillator range.
     pub range: RoscRange,
+    /// Drive strength for oscillator.
     pub drive_strength: [u8; 8],
+    /// Output divider.
     pub div: u16,
 }
 
+/// Crystal oscillator configuration.
 pub struct XoscConfig {
+    /// Final frequency of the oscillator.
     pub hz: u32,
+    /// Configuring PLL for the system clock.
     pub sys_pll: Option<PllConfig>,
+    /// Configuring PLL for the USB clock.
     pub usb_pll: Option<PllConfig>,
+    /// Multiplier for the startup delay.
     pub delay_multiplier: u32,
 }
 
+/// PLL configuration.
 pub struct PllConfig {
+    /// Reference divisor.
     pub refdiv: u8,
+    /// Feedback divisor.
     pub fbdiv: u16,
+    /// Output divisor 1.
     pub post_div1: u8,
+    /// Output divisor 2.
     pub post_div2: u8,
 }
 
+/// Reference
 pub struct RefClkConfig {
     pub src: RefClkSrc,
     pub div: u8,

embassy-rp/src/lib.rs

@@ -1,5 +1,6 @@
 #![no_std]
 #![allow(async_fn_in_trait)]
+#![doc = include_str!("../README.md")]
 
 // This mod MUST go first, so that the others see its macros.
 pub(crate) mod fmt;
@@ -31,9 +32,7 @@ pub mod usb;
 pub mod watchdog;
 
 // PIO
-// TODO: move `pio_instr_util` and `relocate` to inside `pio`
 pub mod pio;
-pub mod pio_instr_util;
 pub(crate) mod relocate;
 
 // Reexports
@@ -302,11 +301,14 @@ fn install_stack_guard(stack_bottom: *mut usize) -> Result<(), ()> {
     Ok(())
 }
 
+/// HAL configuration for RP.
 pub mod config {
     use crate::clocks::ClockConfig;
 
+    /// HAL configuration passed when initializing.
     #[non_exhaustive]
     pub struct Config {
+        /// Clock configuration.
         pub clocks: ClockConfig,
     }
 
@@ -319,12 +321,18 @@ pub mod config {
     }
 
     impl Config {
+        /// Create a new configuration with the provided clock config.
         pub fn new(clocks: ClockConfig) -> Self {
             Self { clocks }
         }
     }
 }
 
+/// Initialize the `embassy-rp` 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::Config) -> Peripherals {
     // Do this first, so that it panics if user is calling `init` a second time
     // before doing anything important.

embassy-rp/src/pio/instr.rs

@@ -1,7 +1,9 @@
+//! Instructions controlling the PIO.
 use pio::{InSource, InstructionOperands, JmpCondition, OutDestination, SetDestination};
 
 use crate::pio::{Instance, StateMachine};
 
+/// Set value of scratch register X.
 pub unsafe fn set_x<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO, SM>, value: u32) {
     const OUT: u16 = InstructionOperands::OUT {
         destination: OutDestination::X,
@@ -12,6 +14,7 @@ pub unsafe fn set_x<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO, S
     sm.exec_instr(OUT);
 }
 
+/// Get value of scratch register X.
 pub unsafe fn get_x<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO, SM>) -> u32 {
     const IN: u16 = InstructionOperands::IN {
         source: InSource::X,
@@ -22,6 +25,7 @@ pub unsafe fn get_x<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO, S
     sm.rx().pull()
 }
 
+/// Set value of scratch register Y.
 pub unsafe fn set_y<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO, SM>, value: u32) {
     const OUT: u16 = InstructionOperands::OUT {
         destination: OutDestination::Y,
@@ -32,6 +36,7 @@ pub unsafe fn set_y<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO, S
     sm.exec_instr(OUT);
 }
 
+/// Get value of scratch register Y.
 pub unsafe fn get_y<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO, SM>) -> u32 {
     const IN: u16 = InstructionOperands::IN {
         source: InSource::Y,
@@ -43,6 +48,7 @@ pub unsafe fn get_y<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO, S
     sm.rx().pull()
 }
 
+/// Set instruction for pindir destination.
 pub unsafe fn set_pindir<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO, SM>, data: u8) {
     let set: u16 = InstructionOperands::SET {
         destination: SetDestination::PINDIRS,
@@ -52,6 +58,7 @@ pub unsafe fn set_pindir<PIO: Instance, const SM: usize>(sm: &mut StateMachine<P
     sm.exec_instr(set);
 }
 
+/// Set instruction for pin destination.
 pub unsafe fn set_pin<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO, SM>, data: u8) {
     let set: u16 = InstructionOperands::SET {
         destination: SetDestination::PINS,
@@ -61,6 +68,7 @@ pub unsafe fn set_pin<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO,
     sm.exec_instr(set);
 }
 
+/// Out instruction for pin destination.
 pub unsafe fn set_out_pin<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO, SM>, data: u32) {
     const OUT: u16 = InstructionOperands::OUT {
         destination: OutDestination::PINS,
@@ -70,6 +78,8 @@ pub unsafe fn set_out_pin<PIO: Instance, const SM: usize>(sm: &mut StateMachine<
     sm.tx().push(data);
     sm.exec_instr(OUT);
 }
+
+/// Out instruction for pindir destination.
 pub unsafe fn set_out_pindir<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO, SM>, data: u32) {
     const OUT: u16 = InstructionOperands::OUT {
         destination: OutDestination::PINDIRS,
@@ -80,6 +90,7 @@ pub unsafe fn set_out_pindir<PIO: Instance, const SM: usize>(sm: &mut StateMachi
     sm.exec_instr(OUT);
 }
 
+/// Jump instruction to address.
 pub unsafe fn exec_jmp<PIO: Instance, const SM: usize>(sm: &mut StateMachine<PIO, SM>, to_addr: u8) {
     let jmp: u16 = InstructionOperands::JMP {
         address: to_addr,

embassy-rp/src/pio/mod.rs

@@ -19,8 +19,11 @@ use crate::gpio::{self, AnyPin, Drive, Level, Pull, SlewRate};
 use crate::interrupt::typelevel::{Binding, Handler, Interrupt};
 use crate::pac::dma::vals::TreqSel;
 use crate::relocate::RelocatedProgram;
-use crate::{pac, peripherals, pio_instr_util, RegExt};
+use crate::{pac, peripherals, RegExt};
 
+pub mod instr;
+
+/// Wakers for interrupts and FIFOs.
 pub struct Wakers([AtomicWaker; 12]);
 
 impl Wakers {
@@ -38,6 +41,7 @@ impl Wakers {
     }
 }
 
+/// FIFO config.
 #[derive(Clone, Copy, PartialEq, Eq, Default, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[repr(u8)]
@@ -51,6 +55,8 @@ pub enum FifoJoin {
     TxOnly,
 }
 
+/// Shift direction.
+#[allow(missing_docs)]
 #[derive(Clone, Copy, PartialEq, Eq, Default, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[repr(u8)]
@@ -60,6 +66,8 @@ pub enum ShiftDirection {
     Left = 0,
 }
 
+/// Pin direction.
+#[allow(missing_docs)]
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[repr(u8)]
@@ -68,12 +76,15 @@ pub enum Direction {
     Out = 1,
 }
 
+/// Which fifo level to use in status check.
 #[derive(Clone, Copy, PartialEq, Eq, Default, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[repr(u8)]
 pub enum StatusSource {
     #[default]
+    /// All-ones if TX FIFO level < N, otherwise all-zeroes.
     TxFifoLevel = 0,
+    /// All-ones if RX FIFO level < N, otherwise all-zeroes.
     RxFifoLevel = 1,
 }
 
@@ -81,6 +92,7 @@ const RXNEMPTY_MASK: u32 = 1 << 0;
 const TXNFULL_MASK: u32 = 1 << 4;
 const SMIRQ_MASK: u32 = 1 << 8;
 
+/// Interrupt handler for PIO.
 pub struct InterruptHandler<PIO: Instance> {
     _pio: PhantomData<PIO>,
 }
@@ -105,6 +117,7 @@ pub struct FifoOutFuture<'a, 'd, PIO: Instance, const SM: usize> {
 }
 
 impl<'a, 'd, PIO: Instance, const SM: usize> FifoOutFuture<'a, 'd, PIO, SM> {
+    /// Create a new future waiting for TX-FIFO to become writable.
     pub fn new(sm: &'a mut StateMachineTx<'d, PIO, SM>, value: u32) -> Self {
         FifoOutFuture { sm_tx: sm, value }
     }
@@ -136,13 +149,14 @@ impl<'a, 'd, PIO: Instance, const SM: usize> Drop for FifoOutFuture<'a, 'd, PIO,
     }
 }
 
-/// Future that waits for RX-FIFO to become readable
+/// Future that waits for RX-FIFO to become readable.
 #[must_use = "futures do nothing unless you `.await` or poll them"]
 pub struct FifoInFuture<'a, 'd, PIO: Instance, const SM: usize> {
     sm_rx: &'a mut StateMachineRx<'d, PIO, SM>,
 }
 
 impl<'a, 'd, PIO: Instance, const SM: usize> FifoInFuture<'a, 'd, PIO, SM> {
+    /// Create future that waits for RX-FIFO to become readable.
     pub fn new(sm: &'a mut StateMachineRx<'d, PIO, SM>) -> Self {
         FifoInFuture { sm_rx: sm }
     }
@@ -207,6 +221,7 @@ impl<'a, 'd, PIO: Instance> Drop for IrqFuture<'a, 'd, PIO> {
     }
 }
 
+/// Type representing a PIO pin.
 pub struct Pin<'l, PIO: Instance> {
     pin: PeripheralRef<'l, AnyPin>,
     pio: PhantomData<PIO>,
@@ -226,7 +241,7 @@ impl<'l, PIO: Instance> Pin<'l, PIO> {
         });
     }
 
-    // Set the pin's slew rate.
+    /// Set the pin's slew rate.
     #[inline]
     pub fn set_slew_rate(&mut self, slew_rate: SlewRate) {
         self.pin.pad_ctrl().modify(|w| {
@@ -251,6 +266,7 @@ impl<'l, PIO: Instance> Pin<'l, PIO> {
         });
     }
 
+    /// Set the pin's input sync bypass.
     pub fn set_input_sync_bypass<'a>(&mut self, bypass: bool) {
         let mask = 1 << self.pin();
         if bypass {
@@ -260,28 +276,34 @@ impl<'l, PIO: Instance> Pin<'l, PIO> {
         }
     }
 
+    /// Get the underlying pin number.
     pub fn pin(&self) -> u8 {
         self.pin._pin()
     }
 }
 
+/// Type representing a state machine RX FIFO.
 pub struct StateMachineRx<'d, PIO: Instance, const SM: usize> {
     pio: PhantomData<&'d mut PIO>,
 }
 
 impl<'d, PIO: Instance, const SM: usize> StateMachineRx<'d, PIO, SM> {
+    /// Check if RX FIFO is empty.
     pub fn empty(&self) -> bool {
         PIO::PIO.fstat().read().rxempty() & (1u8 << SM) != 0
     }
 
+    /// Check if RX FIFO is full.
     pub fn full(&self) -> bool {
         PIO::PIO.fstat().read().rxfull() & (1u8 << SM) != 0
     }
 
+    /// Check RX FIFO level.
     pub fn level(&self) -> u8 {
         (PIO::PIO.flevel().read().0 >> (SM * 8 + 4)) as u8 & 0x0f
     }
 
+    /// Check if state machine has stalled on full RX FIFO.
     pub fn stalled(&self) -> bool {
         let fdebug = PIO::PIO.fdebug();
         let ret = fdebug.read().rxstall() & (1 << SM) != 0;
@@ -291,6 +313,7 @@ impl<'d, PIO: Instance, const SM: usize> StateMachineRx<'d, PIO, SM> {
         ret
     }
 
+    /// Check if RX FIFO underflow (i.e. read-on-empty by the system) has occurred.
     pub fn underflowed(&self) -> bool {
         let fdebug = PIO::PIO.fdebug();
         let ret = fdebug.read().rxunder() & (1 << SM) != 0;
@@ -300,10 +323,12 @@ impl<'d, PIO: Instance, const SM: usize> StateMachineRx<'d, PIO, SM> {
         ret
     }
 
+    /// Pull data from RX FIFO.
     pub fn pull(&mut self) -> u32 {
         PIO::PIO.rxf(SM).read()
     }
 
+    /// Attempt pulling data from RX FIFO.
     pub fn try_pull(&mut self) -> Option<u32> {
         if self.empty() {
             return None;
@@ -311,10 +336,12 @@ impl<'d, PIO: Instance, const SM: usize> StateMachineRx<'d, PIO, SM> {
         Some(self.pull())
     }
 
+    /// Wait for RX FIFO readable.
     pub fn wait_pull<'a>(&'a mut self) -> FifoInFuture<'a, 'd, PIO, SM> {
         FifoInFuture::new(self)
     }
 
+    /// Prepare DMA transfer from RX FIFO.
     pub fn dma_pull<'a, C: Channel, W: Word>(
         &'a mut self,
         ch: PeripheralRef<'a, C>,
@@ -340,22 +367,28 @@ impl<'d, PIO: Instance, const SM: usize> StateMachineRx<'d, PIO, SM> {
     }
 }
 
+/// Type representing a state machine TX FIFO.
 pub struct StateMachineTx<'d, PIO: Instance, const SM: usize> {
     pio: PhantomData<&'d mut PIO>,
 }
 
 impl<'d, PIO: Instance, const SM: usize> StateMachineTx<'d, PIO, SM> {
+    /// Check if TX FIFO is empty.
     pub fn empty(&self) -> bool {
         PIO::PIO.fstat().read().txempty() & (1u8 << SM) != 0
     }
+
+    /// Check if TX FIFO is full.
     pub fn full(&self) -> bool {
         PIO::PIO.fstat().read().txfull() & (1u8 << SM) != 0
     }
 
+    /// Check TX FIFO level.
     pub fn level(&self) -> u8 {
         (PIO::PIO.flevel().read().0 >> (SM * 8)) as u8 & 0x0f
     }
 
+    /// Check state machine has stalled on empty TX FIFO.
     pub fn stalled(&self) -> bool {
         let fdebug = PIO::PIO.fdebug();
         let ret = fdebug.read().txstall() & (1 << SM) != 0;
@@ -365,6 +398,7 @@ impl<'d, PIO: Instance, const SM: usize> StateMachineTx<'d, PIO, SM> {
         ret
     }
 
+    /// Check if FIFO overflowed.
     pub fn overflowed(&self) -> bool {
         let fdebug = PIO::PIO.fdebug();
         let ret = fdebug.read().txover() & (1 << SM) != 0;
@@ -374,10 +408,12 @@ impl<'d, PIO: Instance, const SM: usize> StateMachineTx<'d, PIO, SM> {
         ret
     }
 
+    /// Force push data to TX FIFO.
     pub fn push(&mut self, v: u32) {
         PIO::PIO.txf(SM).write_value(v);
     }
 
+    /// Attempt to push data to TX FIFO.
     pub fn try_push(&mut self, v: u32) -> bool {
         if self.full() {
             return false;
@@ -386,10 +422,12 @@ impl<'d, PIO: Instance, const SM: usize> StateMachineTx<'d, PIO, SM> {
         true
     }
 
+    /// Wait until FIFO is ready for writing.
     pub fn wait_push<'a>(&'a mut self, value: u32) -> FifoOutFuture<'a, 'd, PIO, SM> {
         FifoOutFuture::new(self, value)
     }
 
+    /// Prepare a DMA transfer to TX FIFO.
     pub fn dma_push<'a, C: Channel, W: Word>(&'a mut self, ch: PeripheralRef<'a, C>, data: &'a [W]) -> Transfer<'a, C> {
         let pio_no = PIO::PIO_NO;
         let p = ch.regs();
@@ -411,6 +449,7 @@ impl<'d, PIO: Instance, const SM: usize> StateMachineTx<'d, PIO, SM> {
     }
 }
 
+/// A type representing a single PIO state machine.
 pub struct StateMachine<'d, PIO: Instance, const SM: usize> {
     rx: StateMachineRx<'d, PIO, SM>,
     tx: StateMachineTx<'d, PIO, SM>,
@@ -430,52 +469,78 @@ fn assert_consecutive<'d, PIO: Instance>(pins: &[&Pin<'d, PIO>]) {
     }
 }
 
+/// PIO Execution config.
 #[derive(Clone, Copy, Default, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[non_exhaustive]
 pub struct ExecConfig {
+    /// If true, the MSB of the Delay/Side-set instruction field is used as side-set enable, rather than a side-set data bit.
     pub side_en: bool,
+    /// If true, side-set data is asserted to pin directions, instead of pin values.
     pub side_pindir: bool,
+    /// Pin to trigger jump.
     pub jmp_pin: u8,
+    /// After reaching this address, execution is wrapped to wrap_bottom.
     pub wrap_top: u8,
+    /// After reaching wrap_top, execution is wrapped to this address.
     pub wrap_bottom: u8,
 }
 
+/// PIO shift register config for input or output.
 #[derive(Clone, Copy, Default, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct ShiftConfig {
+    /// Number of bits shifted out of OSR before autopull.
     pub threshold: u8,
+    /// Shift direction.
     pub direction: ShiftDirection,
+    /// For output: Pull automatically output shift register is emptied.
+    /// For input: Push automatically when the input shift register is filled.
     pub auto_fill: bool,
 }
 
+/// PIO pin config.
 #[derive(Clone, Copy, Default, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct PinConfig {
+    /// The number of MSBs of the Delay/Side-set instruction field which are used for side-set.
     pub sideset_count: u8,
+    /// The number of pins asserted by a SET. In the range 0 to 5 inclusive.
     pub set_count: u8,
+    /// The number of pins asserted by an OUT PINS, OUT PINDIRS or MOV PINS instruction. In the range 0 to 32 inclusive.
     pub out_count: u8,
+    /// The pin which is mapped to the least-significant bit of a state machine's IN data bus.
     pub in_base: u8,
+    /// The lowest-numbered pin that will be affected by a side-set operation.
     pub sideset_base: u8,
+    /// The lowest-numbered pin that will be affected by a SET PINS or SET PINDIRS instruction.
     pub set_base: u8,
+    /// The lowest-numbered pin that will be affected by an OUT PINS, OUT PINDIRS or MOV PINS instruction.
     pub out_base: u8,
 }
 
+/// PIO config.
 #[derive(Clone, Copy, Debug)]
 pub struct Config<'d, PIO: Instance> {
-    // CLKDIV
+    /// Clock divisor register for state machines.
     pub clock_divider: FixedU32<U8>,
-    // EXECCTRL
+    /// Which data bit to use for inline OUT enable.
     pub out_en_sel: u8,
+    /// Use a bit of OUT data as an auxiliary write enable When used in conjunction with OUT_STICKY.
     pub inline_out_en: bool,
+    /// Continuously assert the most recent OUT/SET to the pins.
     pub out_sticky: bool,
+    /// Which source to use for checking status.
     pub status_sel: StatusSource,
+    /// Status comparison level.
     pub status_n: u8,
     exec: ExecConfig,
     origin: Option<u8>,
-    // SHIFTCTRL
+    /// Configure FIFO allocation.
     pub fifo_join: FifoJoin,
+    /// Input shifting config.
     pub shift_in: ShiftConfig,
+    /// Output shifting config.
     pub shift_out: ShiftConfig,
     // PINCTRL
     pins: PinConfig,
@@ -505,16 +570,22 @@ impl<'d, PIO: Instance> Default for Config<'d, PIO> {
 }
 
 impl<'d, PIO: Instance> Config<'d, PIO> {
+    /// Get execution configuration.
     pub fn get_exec(&self) -> ExecConfig {
         self.exec
     }
+
+    /// Update execution configuration.
     pub unsafe fn set_exec(&mut self, e: ExecConfig) {
         self.exec = e;
     }
 
+    /// Get pin configuration.
     pub fn get_pins(&self) -> PinConfig {
         self.pins
     }
+
+    /// Update pin configuration.
     pub unsafe fn set_pins(&mut self, p: PinConfig) {
         self.pins = p;
     }
@@ -537,6 +608,7 @@ impl<'d, PIO: Instance> Config<'d, PIO> {
         self.origin = Some(prog.origin);
     }
 
+    /// Set pin used to signal jump.
     pub fn set_jmp_pin(&mut self, pin: &Pin<'d, PIO>) {
         self.exec.jmp_pin = pin.pin();
     }
@@ -571,6 +643,7 @@ impl<'d, PIO: Instance> Config<'d, PIO> {
 }
 
 impl<'d, PIO: Instance + 'd, const SM: usize> StateMachine<'d, PIO, SM> {
+    /// Set the config for a given PIO state machine.
     pub fn set_config(&mut self, config: &Config<'d, PIO>) {
         // sm expects 0 for 65536, truncation makes that happen
         assert!(config.clock_divider <= 65536, "clkdiv must be <= 65536");
@@ -617,7 +690,7 @@ impl<'d, PIO: Instance + 'd, const SM: usize> StateMachine<'d, PIO, SM> {
             w.set_out_base(config.pins.out_base);
         });
         if let Some(origin) = config.origin {
-            unsafe { pio_instr_util::exec_jmp(self, origin) }
+            unsafe { instr::exec_jmp(self, origin) }
         }
     }
 
@@ -626,10 +699,13 @@ impl<'d, PIO: Instance + 'd, const SM: usize> StateMachine<'d, PIO, SM> {
         PIO::PIO.sm(SM)
     }
 
+    /// Restart this state machine.
     pub fn restart(&mut self) {
         let mask = 1u8 << SM;
         PIO::PIO.ctrl().write_set(|w| w.set_sm_restart(mask));
     }
+
+    /// Enable state machine.
     pub fn set_enable(&mut self, enable: bool) {
         let mask = 1u8 << SM;
         if enable {
@@ -639,10 +715,12 @@ impl<'d, PIO: Instance + 'd, const SM: usize> StateMachine<'d, PIO, SM> {
         }
     }
 
+    /// Check if state machine is enabled.
     pub fn is_enabled(&self) -> bool {
         PIO::PIO.ctrl().read().sm_enable() & (1u8 << SM) != 0
     }
 
+    /// Restart a state machine's clock divider from an initial phase of 0.
     pub fn clkdiv_restart(&mut self) {
         let mask = 1u8 << SM;
         PIO::PIO.ctrl().write_set(|w| w.set_clkdiv_restart(mask));
@@ -690,6 +768,7 @@ impl<'d, PIO: Instance + 'd, const SM: usize> StateMachine<'d, PIO, SM> {
         });
     }
 
+    /// Flush FIFOs for state machine.
     pub fn clear_fifos(&mut self) {
         // Toggle FJOIN_RX to flush FIFOs
         let shiftctrl = Self::this_sm().shiftctrl();
@@ -701,21 +780,31 @@ impl<'d, PIO: Instance + 'd, const SM: usize> StateMachine<'d, PIO, SM> {
         });
     }
 
+    /// Instruct state machine to execute a given instructions
+    ///
+    /// SAFETY: The state machine must be in a state where executing
+    /// an arbitrary instruction does not crash it.
     pub unsafe fn exec_instr(&mut self, instr: u16) {
         Self::this_sm().instr().write(|w| w.set_instr(instr));
     }
 
+    /// Return a read handle for reading state machine outputs.
     pub fn rx(&mut self) -> &mut StateMachineRx<'d, PIO, SM> {
         &mut self.rx
     }
+
+    /// Return a handle for writing to inputs.
     pub fn tx(&mut self) -> &mut StateMachineTx<'d, PIO, SM> {
         &mut self.tx
     }
+
+    /// Return both read and write handles for the state machine.
     pub fn rx_tx(&mut self) -> (&mut StateMachineRx<'d, PIO, SM>, &mut StateMachineTx<'d, PIO, SM>) {
         (&mut self.rx, &mut self.tx)
     }
 }
 
+/// PIO handle.
 pub struct Common<'d, PIO: Instance> {
     instructions_used: u32,
     pio: PhantomData<&'d mut PIO>,
@@ -727,18 +816,25 @@ impl<'d, PIO: Instance> Drop for Common<'d, PIO> {
     }
 }
 
+/// Memory of PIO instance.
 pub struct InstanceMemory<'d, PIO: Instance> {
     used_mask: u32,
     pio: PhantomData<&'d mut PIO>,
 }
 
+/// A loaded PIO program.
 pub struct LoadedProgram<'d, PIO: Instance> {
+    /// Memory used by program.
     pub used_memory: InstanceMemory<'d, PIO>,
+    /// Program origin for loading.
     pub origin: u8,
+    /// Wrap controls what to do once program is done executing.
     pub wrap: Wrap,
+    /// Data for 'side' set instruction parameters.
     pub side_set: SideSet,
 }
 
+/// Errors loading a PIO program.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum LoadError {
@@ -834,6 +930,7 @@ impl<'d, PIO: Instance> Common<'d, PIO> {
         self.instructions_used &= !instrs.used_mask;
     }
 
+    /// Bypass flipflop synchronizer on GPIO inputs.
     pub fn set_input_sync_bypass<'a>(&'a mut self, bypass: u32, mask: u32) {
         // this can interfere with per-pin bypass functions. splitting the
         // modification is going to be fine since nothing that relies on
@@ -842,6 +939,7 @@ impl<'d, PIO: Instance> Common<'d, PIO> {
         PIO::PIO.input_sync_bypass().write_clear(|w| *w = mask & !bypass);
     }
 
+    /// Get bypass configuration.
     pub fn get_input_sync_bypass(&self) -> u32 {
         PIO::PIO.input_sync_bypass().read()
     }
@@ -861,6 +959,7 @@ impl<'d, PIO: Instance> Common<'d, PIO> {
         }
     }
 
+    /// Apply changes to all state machines in a batch.
     pub fn apply_sm_batch(&mut self, f: impl FnOnce(&mut PioBatch<'d, PIO>)) {
         let mut batch = PioBatch {
             clkdiv_restart: 0,
@@ -878,6 +977,7 @@ impl<'d, PIO: Instance> Common<'d, PIO> {
     }
 }
 
+/// Represents multiple state machines in a single type.
 pub struct PioBatch<'a, PIO: Instance> {
     clkdiv_restart: u8,
     sm_restart: u8,
@@ -887,25 +987,25 @@ pub struct PioBatch<'a, PIO: Instance> {
 }
 
 impl<'a, PIO: Instance> PioBatch<'a, PIO> {
-    pub fn restart_clockdiv<const SM: usize>(&mut self, _sm: &mut StateMachine<'a, PIO, SM>) {
-        self.clkdiv_restart |= 1 << SM;
-    }
-
+    /// Restart a state machine's clock divider from an initial phase of 0.
     pub fn restart<const SM: usize>(&mut self, _sm: &mut StateMachine<'a, PIO, SM>) {
         self.clkdiv_restart |= 1 << SM;
     }
 
+    /// Enable a specific state machine.
     pub fn set_enable<const SM: usize>(&mut self, _sm: &mut StateMachine<'a, PIO, SM>, enable: bool) {
         self.sm_enable_mask |= 1 << SM;
         self.sm_enable |= (enable as u8) << SM;
     }
 }
 
+/// Type representing a PIO interrupt.
 pub struct Irq<'d, PIO: Instance, const N: usize> {
     pio: PhantomData<&'d mut PIO>,
 }
 
 impl<'d, PIO: Instance, const N: usize> Irq<'d, PIO, N> {
+    /// Wait for an IRQ to fire.
     pub fn wait<'a>(&'a mut self) -> IrqFuture<'a, 'd, PIO> {
         IrqFuture {
             pio: PhantomData,
@@ -914,59 +1014,79 @@ impl<'d, PIO: Instance, const N: usize> Irq<'d, PIO, N> {
     }
 }
 
+/// Interrupt flags for a PIO instance.
 #[derive(Clone)]
 pub struct IrqFlags<'d, PIO: Instance> {
     pio: PhantomData<&'d mut PIO>,
 }
 
 impl<'d, PIO: Instance> IrqFlags<'d, PIO> {
+    /// Check if interrupt fired.
     pub fn check(&self, irq_no: u8) -> bool {
         assert!(irq_no < 8);
         self.check_any(1 << irq_no)
     }
 
+    /// Check if any of the interrupts in the bitmap fired.
     pub fn check_any(&self, irqs: u8) -> bool {
         PIO::PIO.irq().read().irq() & irqs != 0
     }
 
+    /// Check if all interrupts have fired.
     pub fn check_all(&self, irqs: u8) -> bool {
         PIO::PIO.irq().read().irq() & irqs == irqs
     }
 
+    /// Clear interrupt for interrupt number.
     pub fn clear(&self, irq_no: usize) {
         assert!(irq_no < 8);
         self.clear_all(1 << irq_no);
     }
 
+    /// Clear all interrupts set in the bitmap.
     pub fn clear_all(&self, irqs: u8) {
         PIO::PIO.irq().write(|w| w.set_irq(irqs))
     }
 
+    /// Fire a given interrupt.
     pub fn set(&self, irq_no: usize) {
         assert!(irq_no < 8);
         self.set_all(1 << irq_no);
     }
 
+    /// Fire all interrupts.
     pub fn set_all(&self, irqs: u8) {
         PIO::PIO.irq_force().write(|w| w.set_irq_force(irqs))
     }
 }
 
+/// An instance of the PIO driver.
 pub struct Pio<'d, PIO: Instance> {
+    /// PIO handle.
     pub common: Common<'d, PIO>,
+    /// PIO IRQ flags.
     pub irq_flags: IrqFlags<'d, PIO>,
+    /// IRQ0 configuration.
     pub irq0: Irq<'d, PIO, 0>,
+    /// IRQ1 configuration.
     pub irq1: Irq<'d, PIO, 1>,
+    /// IRQ2 configuration.
     pub irq2: Irq<'d, PIO, 2>,
+    /// IRQ3 configuration.
     pub irq3: Irq<'d, PIO, 3>,
+    /// State machine 0 handle.
     pub sm0: StateMachine<'d, PIO, 0>,
+    /// State machine 1 handle.
     pub sm1: StateMachine<'d, PIO, 1>,
+    /// State machine 2 handle.
     pub sm2: StateMachine<'d, PIO, 2>,
+    /// State machine 3 handle.
     pub sm3: StateMachine<'d, PIO, 3>,
     _pio: PhantomData<&'d mut PIO>,
 }
 
 impl<'d, PIO: Instance> Pio<'d, PIO> {
+    /// Create a new instance of a PIO peripheral.
     pub fn new(_pio: impl Peripheral<P = PIO> + 'd, _irq: impl Binding<PIO::Interrupt, InterruptHandler<PIO>>) -> Self {
         PIO::state().users.store(5, Ordering::Release);
         PIO::state().used_pins.store(0, Ordering::Release);
@@ -1003,9 +1123,10 @@ impl<'d, PIO: Instance> Pio<'d, PIO> {
     }
 }
 
-// we need to keep a record of which pins are assigned to each PIO. make_pio_pin
-// notionally takes ownership of the pin it is given, but the wrapped pin cannot
-// be treated as an owned resource since dropping it would have to deconfigure
+/// Representation of the PIO state keeping a record of which pins are assigned to
+/// each PIO.
+// make_pio_pin notionally takes ownership of the pin it is given, but the wrapped pin
+// cannot be treated as an owned resource since dropping it would have to deconfigure
 // the pin, breaking running state machines in the process. pins are also shared
 // between all state machines, which makes ownership even messier to track any
 // other way.
@@ -1059,6 +1180,7 @@ mod sealed {
     }
 }
 
+/// PIO instance.
 pub trait Instance: sealed::Instance + Sized + Unpin {}
 
 macro_rules! impl_pio {
@@ -1076,6 +1198,7 @@ macro_rules! impl_pio {
 impl_pio!(PIO0, 0, PIO0, PIO0_0, PIO0_IRQ_0);
 impl_pio!(PIO1, 1, PIO1, PIO1_0, PIO1_IRQ_0);
 
+/// PIO pin.
 pub trait PioPin: sealed::PioPin + gpio::Pin {}
 
 macro_rules! impl_pio_pin {

embassy-rp/src/pwm.rs

@@ -61,9 +61,13 @@ impl Default for Config {
     }
 }
 
+/// PWM input mode.
 pub enum InputMode {
+    /// Level mode.
     Level,
+    /// Rising edge mode.
     RisingEdge,
+    /// Falling edge mode.
     FallingEdge,
 }
 
@@ -77,6 +81,7 @@ impl From<InputMode> for Divmode {
     }
 }
 
+/// PWM driver.
 pub struct Pwm<'d, T: Channel> {
     inner: PeripheralRef<'d, T>,
     pin_a: Option<PeripheralRef<'d, AnyPin>>,

embassy-rp/src/rtc/mod.rs

@@ -194,6 +194,7 @@ mod sealed {
     }
 }
 
+/// RTC peripheral instance.
 pub trait Instance: sealed::Instance {}
 
 impl sealed::Instance for crate::peripherals::RTC {

embassy-rp/src/spi.rs

@@ -11,6 +11,7 @@ use crate::gpio::sealed::Pin as _;
 use crate::gpio::{AnyPin, Pin as GpioPin};
 use crate::{pac, peripherals, Peripheral};
 
+/// SPI errors.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[non_exhaustive]
@@ -18,11 +19,15 @@ pub enum Error {
     // No errors for now
 }
 
+/// SPI configuration.
 #[non_exhaustive]
 #[derive(Clone)]
 pub struct Config {
+    /// Frequency.
     pub frequency: u32,
+    /// Phase.
     pub phase: Phase,
+    /// Polarity.
     pub polarity: Polarity,
 }
 
@@ -36,6 +41,7 @@ impl Default for Config {
     }
 }
 
+/// SPI driver.
 pub struct Spi<'d, T: Instance, M: Mode> {
     inner: PeripheralRef<'d, T>,
     tx_dma: Option<PeripheralRef<'d, AnyChannel>>,
@@ -119,6 +125,7 @@ impl<'d, T: Instance, M: Mode> Spi<'d, T, M> {
         }
     }
 
+    /// Write data to SPI blocking execution until done.
     pub fn blocking_write(&mut self, data: &[u8]) -> Result<(), Error> {
         let p = self.inner.regs();
         for &b in data {
@@ -131,6 +138,7 @@ impl<'d, T: Instance, M: Mode> Spi<'d, T, M> {
         Ok(())
     }
 
+    /// Transfer data in place to SPI blocking execution until done.
     pub fn blocking_transfer_in_place(&mut self, data: &mut [u8]) -> Result<(), Error> {
         let p = self.inner.regs();
         for b in data {
@@ -143,6 +151,7 @@ impl<'d, T: Instance, M: Mode> Spi<'d, T, M> {
         Ok(())
     }
 
+    /// Read data from SPI blocking execution until done.
     pub fn blocking_read(&mut self, data: &mut [u8]) -> Result<(), Error> {
         let p = self.inner.regs();
         for b in data {
@@ -155,6 +164,7 @@ impl<'d, T: Instance, M: Mode> Spi<'d, T, M> {
         Ok(())
     }
 
+    /// Transfer data to SPI blocking execution until done.
     pub fn blocking_transfer(&mut self, read: &mut [u8], write: &[u8]) -> Result<(), Error> {
         let p = self.inner.regs();
         let len = read.len().max(write.len());
@@ -172,12 +182,14 @@ impl<'d, T: Instance, M: Mode> Spi<'d, T, M> {
         Ok(())
     }
 
+    /// Block execution until SPI is done.
     pub fn flush(&mut self) -> Result<(), Error> {
         let p = self.inner.regs();
         while p.sr().read().bsy() {}
         Ok(())
     }
 
+    /// Set SPI frequency.
     pub fn set_frequency(&mut self, freq: u32) {
         let (presc, postdiv) = calc_prescs(freq);
         let p = self.inner.regs();
@@ -196,6 +208,7 @@ impl<'d, T: Instance, M: Mode> Spi<'d, T, M> {
 }
 
 impl<'d, T: Instance> Spi<'d, T, Blocking> {
+    /// Create an SPI driver in blocking mode.
     pub fn new_blocking(
         inner: impl Peripheral<P = T> + 'd,
         clk: impl Peripheral<P = impl ClkPin<T> + 'd> + 'd,
@@ -216,6 +229,7 @@ impl<'d, T: Instance> Spi<'d, T, Blocking> {
         )
     }
 
+    /// Create an SPI driver in blocking mode supporting writes only.
     pub fn new_blocking_txonly(
         inner: impl Peripheral<P = T> + 'd,
         clk: impl Peripheral<P = impl ClkPin<T> + 'd> + 'd,
@@ -235,6 +249,7 @@ impl<'d, T: Instance> Spi<'d, T, Blocking> {
         )
     }
 
+    /// Create an SPI driver in blocking mode supporting reads only.
     pub fn new_blocking_rxonly(
         inner: impl Peripheral<P = T> + 'd,
         clk: impl Peripheral<P = impl ClkPin<T> + 'd> + 'd,
@@ -256,6 +271,7 @@ impl<'d, T: Instance> Spi<'d, T, Blocking> {
 }
 
 impl<'d, T: Instance> Spi<'d, T, Async> {
+    /// Create an SPI driver in async mode supporting DMA operations.
     pub fn new(
         inner: impl Peripheral<P = T> + 'd,
         clk: impl Peripheral<P = impl ClkPin<T> + 'd> + 'd,
@@ -278,6 +294,7 @@ impl<'d, T: Instance> Spi<'d, T, Async> {
         )
     }
 
+    /// Create an SPI driver in async mode supporting DMA write operations only.
     pub fn new_txonly(
         inner: impl Peripheral<P = T> + 'd,
         clk: impl Peripheral<P = impl ClkPin<T> + 'd> + 'd,
@@ -298,6 +315,7 @@ impl<'d, T: Instance> Spi<'d, T, Async> {
         )
     }
 
+    /// Create an SPI driver in async mode supporting DMA read operations only.
     pub fn new_rxonly(
         inner: impl Peripheral<P = T> + 'd,
         clk: impl Peripheral<P = impl ClkPin<T> + 'd> + 'd,
@@ -318,6 +336,7 @@ impl<'d, T: Instance> Spi<'d, T, Async> {
         )
     }
 
+    /// Write data to SPI using DMA.
     pub async fn write(&mut self, buffer: &[u8]) -> Result<(), Error> {
         let tx_ch = self.tx_dma.as_mut().unwrap();
         let tx_transfer = unsafe {
@@ -340,6 +359,7 @@ impl<'d, T: Instance> Spi<'d, T, Async> {
         Ok(())
     }
 
+    /// Read data from SPI using DMA.
     pub async fn read(&mut self, buffer: &mut [u8]) -> Result<(), Error> {
         // Start RX first. Transfer starts when TX starts, if RX
         // is not started yet we might lose bytes.
@@ -365,10 +385,12 @@ impl<'d, T: Instance> Spi<'d, T, Async> {
         Ok(())
     }
 
+    /// Transfer data to SPI using DMA.
     pub async fn transfer(&mut self, rx_buffer: &mut [u8], tx_buffer: &[u8]) -> Result<(), Error> {
         self.transfer_inner(rx_buffer, tx_buffer).await
     }
 
+    /// Transfer data in place to SPI using DMA.
     pub async fn transfer_in_place(&mut self, words: &mut [u8]) -> Result<(), Error> {
         self.transfer_inner(words, words).await
     }
@@ -434,7 +456,10 @@ mod sealed {
     }
 }
 
+/// Mode.
 pub trait Mode: sealed::Mode {}
+
+/// SPI instance trait.
 pub trait Instance: sealed::Instance {}
 
 macro_rules! impl_instance {
@@ -454,9 +479,13 @@ macro_rules! impl_instance {
 impl_instance!(SPI0, Spi0, 16, 17);
 impl_instance!(SPI1, Spi1, 18, 19);
 
+/// CLK pin.
 pub trait ClkPin<T: Instance>: GpioPin {}
+/// CS pin.
 pub trait CsPin<T: Instance>: GpioPin {}
+/// MOSI pin.
 pub trait MosiPin<T: Instance>: GpioPin {}
+/// MISO pin.
 pub trait MisoPin<T: Instance>: GpioPin {}
 
 macro_rules! impl_pin {
@@ -503,7 +532,9 @@ macro_rules! impl_mode {
     };
 }
 
+/// Blocking mode.
 pub struct Blocking;
+/// Async mode.
 pub struct Async;
 
 impl_mode!(Blocking);

embassy-rp/src/uart/buffered.rs

@@ -38,15 +38,18 @@ impl State {
     }
 }
 
+/// Buffered UART driver.
 pub struct BufferedUart<'d, T: Instance> {
     pub(crate) rx: BufferedUartRx<'d, T>,
     pub(crate) tx: BufferedUartTx<'d, T>,
 }
 
+/// Buffered UART RX handle.
 pub struct BufferedUartRx<'d, T: Instance> {
     pub(crate) phantom: PhantomData<&'d mut T>,
 }
 
+/// Buffered UART TX handle.
 pub struct BufferedUartTx<'d, T: Instance> {
     pub(crate) phantom: PhantomData<&'d mut T>,
 }
@@ -84,6 +87,7 @@ pub(crate) fn init_buffers<'d, T: Instance + 'd>(
 }
 
 impl<'d, T: Instance> BufferedUart<'d, T> {
+    /// Create a buffered UART instance.
     pub fn new(
         _uart: impl Peripheral<P = T> + 'd,
         irq: impl Binding<T::Interrupt, BufferedInterruptHandler<T>>,
@@ -104,6 +108,7 @@ impl<'d, T: Instance> BufferedUart<'d, T> {
         }
     }
 
+    /// Create a buffered UART instance with flow control.
     pub fn new_with_rtscts(
         _uart: impl Peripheral<P = T> + 'd,
         irq: impl Binding<T::Interrupt, BufferedInterruptHandler<T>>,
@@ -132,32 +137,39 @@ impl<'d, T: Instance> BufferedUart<'d, T> {
         }
     }
 
+    /// Write to UART TX buffer blocking execution until done.
     pub fn blocking_write(&mut self, buffer: &[u8]) -> Result<usize, Error> {
         self.tx.blocking_write(buffer)
     }
 
+    /// Flush UART TX blocking execution until done.
     pub fn blocking_flush(&mut self) -> Result<(), Error> {
         self.tx.blocking_flush()
     }
 
+    /// Read from UART RX buffer blocking execution until done.
     pub fn blocking_read(&mut self, buffer: &mut [u8]) -> Result<usize, Error> {
         self.rx.blocking_read(buffer)
     }
 
+    /// Check if UART is busy transmitting.
     pub fn busy(&self) -> bool {
         self.tx.busy()
     }
 
+    /// Wait until TX is empty and send break condition.
     pub async fn send_break(&mut self, bits: u32) {
         self.tx.send_break(bits).await
     }
 
+    /// Split into separate RX and TX handles.
     pub fn split(self) -> (BufferedUartRx<'d, T>, BufferedUartTx<'d, T>) {
         (self.rx, self.tx)
     }
 }
 
 impl<'d, T: Instance> BufferedUartRx<'d, T> {
+    /// Create a new buffered UART RX.
     pub fn new(
         _uart: impl Peripheral<P = T> + 'd,
         irq: impl Binding<T::Interrupt, BufferedInterruptHandler<T>>,
@@ -173,6 +185,7 @@ impl<'d, T: Instance> BufferedUartRx<'d, T> {
         Self { phantom: PhantomData }
     }
 
+    /// Create a new buffered UART RX with flow control.
     pub fn new_with_rts(
         _uart: impl Peripheral<P = T> + 'd,
         irq: impl Binding<T::Interrupt, BufferedInterruptHandler<T>>,
@@ -253,6 +266,7 @@ impl<'d, T: Instance> BufferedUartRx<'d, T> {
         Poll::Ready(result)
     }
 
+    /// Read from UART RX buffer blocking execution until done.
     pub fn blocking_read(&mut self, buf: &mut [u8]) -> Result<usize, Error> {
         loop {
             match Self::try_read(buf) {
@@ -303,6 +317,7 @@ impl<'d, T: Instance> BufferedUartRx<'d, T> {
 }
 
 impl<'d, T: Instance> BufferedUartTx<'d, T> {
+    /// Create a new buffered UART TX.
     pub fn new(
         _uart: impl Peripheral<P = T> + 'd,
         irq: impl Binding<T::Interrupt, BufferedInterruptHandler<T>>,
@@ -318,6 +333,7 @@ impl<'d, T: Instance> BufferedUartTx<'d, T> {
         Self { phantom: PhantomData }
     }
 
+    /// Create a new buffered UART TX with flow control.
     pub fn new_with_cts(
         _uart: impl Peripheral<P = T> + 'd,
         irq: impl Binding<T::Interrupt, BufferedInterruptHandler<T>>,
@@ -373,6 +389,7 @@ impl<'d, T: Instance> BufferedUartTx<'d, T> {
         })
     }
 
+    /// Write to UART TX buffer blocking execution until done.
     pub fn blocking_write(&mut self, buf: &[u8]) -> Result<usize, Error> {
         if buf.is_empty() {
             return Ok(0);
@@ -398,6 +415,7 @@ impl<'d, T: Instance> BufferedUartTx<'d, T> {
         }
     }
 
+    /// Flush UART TX blocking execution until done.
     pub fn blocking_flush(&mut self) -> Result<(), Error> {
         loop {
             let state = T::buffered_state();
@@ -407,6 +425,7 @@ impl<'d, T: Instance> BufferedUartTx<'d, T> {
         }
     }
 
+    /// Check if UART is busy.
     pub fn busy(&self) -> bool {
         T::regs().uartfr().read().busy()
     }
@@ -466,6 +485,7 @@ impl<'d, T: Instance> Drop for BufferedUartTx<'d, T> {
     }
 }
 
+/// Interrupt handler.
 pub struct BufferedInterruptHandler<T: Instance> {
     _uart: PhantomData<T>,
 }

embassy-rp/src/uart/mod.rs

@@ -20,11 +20,16 @@ use crate::{interrupt, pac, peripherals, Peripheral, RegExt};
 mod buffered;
 pub use buffered::{BufferedInterruptHandler, BufferedUart, BufferedUartRx, BufferedUartTx};
 
+/// Word length.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub enum DataBits {
+    /// 5 bits.
     DataBits5,
+    /// 6 bits.
     DataBits6,
+    /// 7 bits.
     DataBits7,
+    /// 8 bits.
     DataBits8,
 }
 
@@ -39,13 +44,18 @@ impl DataBits {
     }
 }
 
+/// Parity bit.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub enum Parity {
+    /// No parity.
     ParityNone,
+    /// Even parity.
     ParityEven,
+    /// Odd parity.
     ParityOdd,
 }
 
+/// Stop bits.
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub enum StopBits {
     #[doc = "1 stop bit"]
@@ -54,20 +64,25 @@ pub enum StopBits {
     STOP2,
 }
 
+/// UART config.
 #[non_exhaustive]
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub struct Config {
+    /// Baud rate.
     pub baudrate: u32,
+    /// Word length.
     pub data_bits: DataBits,
+    /// Stop bits.
     pub stop_bits: StopBits,
+    /// Parity bit.
     pub parity: Parity,
     /// Invert the tx pin output
     pub invert_tx: bool,
     /// Invert the rx pin input
     pub invert_rx: bool,
-    // Invert the rts pin
+    /// Invert the rts pin
     pub invert_rts: bool,
-    // Invert the cts pin
+    /// Invert the cts pin
     pub invert_cts: bool,
 }
 
@@ -102,21 +117,25 @@ pub enum Error {
     Framing,
 }
 
+/// Internal DMA state of UART RX.
 pub struct DmaState {
     rx_err_waker: AtomicWaker,
     rx_errs: AtomicU16,
 }
 
+/// UART driver.
 pub struct Uart<'d, T: Instance, M: Mode> {
     tx: UartTx<'d, T, M>,
     rx: UartRx<'d, T, M>,
 }
 
+/// UART TX driver.
 pub struct UartTx<'d, T: Instance, M: Mode> {
     tx_dma: Option<PeripheralRef<'d, AnyChannel>>,
     phantom: PhantomData<(&'d mut T, M)>,
 }
 
+/// UART RX driver.
 pub struct UartRx<'d, T: Instance, M: Mode> {
     rx_dma: Option<PeripheralRef<'d, AnyChannel>>,
     phantom: PhantomData<(&'d mut T, M)>,
@@ -142,6 +161,7 @@ impl<'d, T: Instance, M: Mode> UartTx<'d, T, M> {
         }
     }
 
+    /// Transmit the provided buffer blocking execution until done.
     pub fn blocking_write(&mut self, buffer: &[u8]) -> Result<(), Error> {
         let r = T::regs();
         for &b in buffer {
@@ -151,12 +171,14 @@ impl<'d, T: Instance, M: Mode> UartTx<'d, T, M> {
         Ok(())
     }
 
+    /// Flush UART TX blocking execution until done.
     pub fn blocking_flush(&mut self) -> Result<(), Error> {
         let r = T::regs();
         while !r.uartfr().read().txfe() {}
         Ok(())
     }
 
+    /// Check if UART is busy transmitting.
     pub fn busy(&self) -> bool {
         T::regs().uartfr().read().busy()
     }
@@ -191,6 +213,8 @@ impl<'d, T: Instance, M: Mode> UartTx<'d, T, M> {
 }
 
 impl<'d, T: Instance> UartTx<'d, T, Blocking> {
+    /// Convert this uart TX instance into a buffered uart using the provided
+    /// irq and transmit buffer.
     pub fn into_buffered(
         self,
         irq: impl Binding<T::Interrupt, BufferedInterruptHandler<T>>,
@@ -203,6 +227,7 @@ impl<'d, T: Instance> UartTx<'d, T, Blocking> {
 }
 
 impl<'d, T: Instance> UartTx<'d, T, Async> {
+    /// Write to UART TX from the provided buffer using DMA.
     pub async fn write(&mut self, buffer: &[u8]) -> Result<(), Error> {
         let ch = self.tx_dma.as_mut().unwrap();
         let transfer = unsafe {
@@ -246,6 +271,7 @@ impl<'d, T: Instance, M: Mode> UartRx<'d, T, M> {
         }
     }
 
+    /// Read from UART RX blocking execution until done.
     pub fn blocking_read(&mut self, mut buffer: &mut [u8]) -> Result<(), Error> {
         while buffer.len() > 0 {
             let received = self.drain_fifo(buffer)?;
@@ -294,6 +320,7 @@ impl<'d, T: Instance, M: Mode> Drop for UartRx<'d, T, M> {
 }
 
 impl<'d, T: Instance> UartRx<'d, T, Blocking> {
+    /// Create a new UART RX instance for blocking mode operations.
     pub fn new_blocking(
         _uart: impl Peripheral<P = T> + 'd,
         rx: impl Peripheral<P = impl RxPin<T>> + 'd,
@@ -304,6 +331,8 @@ impl<'d, T: Instance> UartRx<'d, T, Blocking> {
         Self::new_inner(false, None)
     }
 
+    /// Convert this uart RX instance into a buffered uart using the provided
+    /// irq and receive buffer.
     pub fn into_buffered(
         self,
         irq: impl Binding<T::Interrupt, BufferedInterruptHandler<T>>,
@@ -315,6 +344,7 @@ impl<'d, T: Instance> UartRx<'d, T, Blocking> {
     }
 }
 
+/// Interrupt handler.
 pub struct InterruptHandler<T: Instance> {
     _uart: PhantomData<T>,
 }
@@ -338,6 +368,7 @@ impl<T: Instance> interrupt::typelevel::Handler<T::Interrupt> for InterruptHandl
 }
 
 impl<'d, T: Instance> UartRx<'d, T, Async> {
+    /// Read from UART RX into the provided buffer.
     pub async fn read(&mut self, buffer: &mut [u8]) -> Result<(), Error> {
         // clear error flags before we drain the fifo. errors that have accumulated
         // in the flags will also be present in the fifo.
@@ -458,6 +489,8 @@ impl<'d, T: Instance> Uart<'d, T, Blocking> {
         )
     }
 
+    /// Convert this uart instance into a buffered uart using the provided
+    /// irq, transmit and receive buffers.
     pub fn into_buffered(
         self,
         irq: impl Binding<T::Interrupt, BufferedInterruptHandler<T>>,
@@ -667,22 +700,27 @@ impl<'d, T: Instance + 'd, M: Mode> Uart<'d, T, M> {
 }
 
 impl<'d, T: Instance, M: Mode> Uart<'d, T, M> {
+    /// Transmit the provided buffer blocking execution until done.
     pub fn blocking_write(&mut self, buffer: &[u8]) -> Result<(), Error> {
         self.tx.blocking_write(buffer)
     }
 
+    /// Flush UART TX blocking execution until done.
     pub fn blocking_flush(&mut self) -> Result<(), Error> {
         self.tx.blocking_flush()
     }
 
+    /// Read from UART RX blocking execution until done.
     pub fn blocking_read(&mut self, buffer: &mut [u8]) -> Result<(), Error> {
         self.rx.blocking_read(buffer)
     }
 
+    /// Check if UART is busy transmitting.
     pub fn busy(&self) -> bool {
         self.tx.busy()
     }
 
+    /// Wait until TX is empty and send break condition.
     pub async fn send_break(&mut self, bits: u32) {
         self.tx.send_break(bits).await
     }
@@ -695,10 +733,12 @@ impl<'d, T: Instance, M: Mode> Uart<'d, T, M> {
 }
 
 impl<'d, T: Instance> Uart<'d, T, Async> {
+    /// Write to UART TX from the provided buffer.
     pub async fn write(&mut self, buffer: &[u8]) -> Result<(), Error> {
         self.tx.write(buffer).await
     }
 
+    /// Read from UART RX into the provided buffer.
     pub async fn read(&mut self, buffer: &mut [u8]) -> Result<(), Error> {
         self.rx.read(buffer).await
     }
@@ -889,6 +929,7 @@ mod sealed {
     pub trait RtsPin<T: Instance> {}
 }
 
+/// UART mode.
 pub trait Mode: sealed::Mode {}
 
 macro_rules! impl_mode {
@@ -898,12 +939,15 @@ macro_rules! impl_mode {
     };
 }
 
+/// Blocking mode.
 pub struct Blocking;
+/// Async mode.
 pub struct Async;
 
 impl_mode!(Blocking);
 impl_mode!(Async);
 
+/// UART instance trait.
 pub trait Instance: sealed::Instance {}
 
 macro_rules! impl_instance {
@@ -938,9 +982,13 @@ macro_rules! impl_instance {
 impl_instance!(UART0, UART0_IRQ, 20, 21);
 impl_instance!(UART1, UART1_IRQ, 22, 23);
 
+/// Trait for TX pins.
 pub trait TxPin<T: Instance>: sealed::TxPin<T> + crate::gpio::Pin {}
+/// Trait for RX pins.
 pub trait RxPin<T: Instance>: sealed::RxPin<T> + crate::gpio::Pin {}
+/// Trait for Clear To Send (CTS) pins.
 pub trait CtsPin<T: Instance>: sealed::CtsPin<T> + crate::gpio::Pin {}
+/// Trait for Request To Send (RTS) pins.
 pub trait RtsPin<T: Instance>: sealed::RtsPin<T> + crate::gpio::Pin {}
 
 macro_rules! impl_pin {

embassy-rp/src/usb.rs

@@ -20,7 +20,9 @@ pub(crate) mod sealed {
     }
 }
 
+/// USB peripheral instance.
 pub trait Instance: sealed::Instance + 'static {
+    /// Interrupt for this peripheral.
     type Interrupt: interrupt::typelevel::Interrupt;
 }
 
@@ -96,6 +98,7 @@ impl EndpointData {
     }
 }
 
+/// RP2040 USB driver handle.
 pub struct Driver<'d, T: Instance> {
     phantom: PhantomData<&'d mut T>,
     ep_in: [EndpointData; EP_COUNT],
@@ -104,6 +107,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 Binding<T::Interrupt, InterruptHandler<T>>) -> Self {
         T::Interrupt::unpend();
         unsafe { T::Interrupt::enable() };
@@ -240,6 +244,7 @@ impl<'d, T: Instance> Driver<'d, T> {
     }
 }
 
+/// USB interrupt handler.
 pub struct InterruptHandler<T: Instance> {
     _uart: PhantomData<T>,
 }
@@ -342,6 +347,7 @@ impl<'d, T: Instance> driver::Driver<'d> for Driver<'d, T> {
     }
 }
 
+/// Type representing the RP USB bus.
 pub struct Bus<'d, T: Instance> {
     phantom: PhantomData<&'d mut T>,
     ep_out: [EndpointData; EP_COUNT],
@@ -461,6 +467,7 @@ trait Dir {
     fn waker(i: usize) -> &'static AtomicWaker;
 }
 
+/// Type for In direction.
 pub enum In {}
 impl Dir for In {
     fn dir() -> Direction {
@@ -473,6 +480,7 @@ impl Dir for In {
     }
 }
 
+/// Type for Out direction.
 pub enum Out {}
 impl Dir for Out {
     fn dir() -> Direction {
@@ -485,6 +493,7 @@ impl Dir for Out {
     }
 }
 
+/// Endpoint for RP USB driver.
 pub struct Endpoint<'d, T: Instance, D> {
     _phantom: PhantomData<(&'d mut T, D)>,
     info: EndpointInfo,
@@ -616,6 +625,7 @@ impl<'d, T: Instance> driver::EndpointIn for Endpoint<'d, T, In> {
     }
 }
 
+/// Control pipe for RP USB driver.
 pub struct ControlPipe<'d, T: Instance> {
     _phantom: PhantomData<&'d mut T>,
     max_packet_size: u16,

embassy-stm32/build.rs

@@ -672,14 +672,14 @@ fn main() {
         (("lpuart", "RTS"), quote!(crate::usart::RtsPin)),
         (("lpuart", "CK"), quote!(crate::usart::CkPin)),
         (("lpuart", "DE"), quote!(crate::usart::DePin)),
-        (("sai", "SCK_A"), quote!(crate::sai::SckAPin)),
-        (("sai", "SCK_B"), quote!(crate::sai::SckBPin)),
-        (("sai", "FS_A"), quote!(crate::sai::FsAPin)),
-        (("sai", "FS_B"), quote!(crate::sai::FsBPin)),
-        (("sai", "SD_A"), quote!(crate::sai::SdAPin)),
-        (("sai", "SD_B"), quote!(crate::sai::SdBPin)),
-        (("sai", "MCLK_A"), quote!(crate::sai::MclkAPin)),
-        (("sai", "MCLK_B"), quote!(crate::sai::MclkBPin)),
+        (("sai", "SCK_A"), quote!(crate::sai::SckPin<A>)),
+        (("sai", "SCK_B"), quote!(crate::sai::SckPin<B>)),
+        (("sai", "FS_A"), quote!(crate::sai::FsPin<A>)),
+        (("sai", "FS_B"), quote!(crate::sai::FsPin<B>)),
+        (("sai", "SD_A"), quote!(crate::sai::SdPin<A>)),
+        (("sai", "SD_B"), quote!(crate::sai::SdPin<B>)),
+        (("sai", "MCLK_A"), quote!(crate::sai::MclkPin<A>)),
+        (("sai", "MCLK_B"), quote!(crate::sai::MclkPin<B>)),
         (("sai", "WS"), quote!(crate::sai::WsPin)),
         (("spi", "SCK"), quote!(crate::spi::SckPin)),
         (("spi", "MOSI"), quote!(crate::spi::MosiPin)),
@@ -995,8 +995,8 @@ fn main() {
         (("usart", "TX"), quote!(crate::usart::TxDma)),
         (("lpuart", "RX"), quote!(crate::usart::RxDma)),
         (("lpuart", "TX"), quote!(crate::usart::TxDma)),
-        (("sai", "A"), quote!(crate::sai::DmaA)),
-        (("sai", "B"), quote!(crate::sai::DmaB)),
+        (("sai", "A"), quote!(crate::sai::Dma<A>)),
+        (("sai", "B"), quote!(crate::sai::Dma<B>)),
         (("spi", "RX"), quote!(crate::spi::RxDma)),
         (("spi", "TX"), quote!(crate::spi::TxDma)),
         (("i2c", "RX"), quote!(crate::i2c::RxDma)),

embassy-stm32/src/adc/mod.rs

@@ -1,5 +1,7 @@
-//! Analog to Digital (ADC) converter driver.
+//! Analog to Digital Converter (ADC)
+
 #![macro_use]
+#![allow(missing_docs)] // TODO
 
 #[cfg(not(adc_f3_v2))]
 #[cfg_attr(adc_f1, path = "f1.rs")]

embassy-stm32/src/can/bxcan.rs

@@ -21,8 +21,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 +45,7 @@ impl<T: Instance> interrupt::typelevel::Handler<T::TXInterrupt> for TxInterruptH
     }
 }
 
+/// RX0 interrupt handler.
 pub struct Rx0InterruptHandler<T: Instance> {
     _phantom: PhantomData<T>,
 }
@@ -54,6 +57,7 @@ impl<T: Instance> interrupt::typelevel::Handler<T::RX0Interrupt> for Rx0Interrup
     }
 }
 
+/// RX1 interrupt handler.
 pub struct Rx1InterruptHandler<T: Instance> {
     _phantom: PhantomData<T>,
 }
@@ -65,6 +69,7 @@ impl<T: Instance> interrupt::typelevel::Handler<T::RX1Interrupt> for Rx1Interrup
     }
 }
 
+/// SCE interrupt handler.
 pub struct SceInterruptHandler<T: Instance> {
     _phantom: PhantomData<T>,
 }
@@ -82,10 +87,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 +109,7 @@ pub enum BusError {
     BusWarning,
 }
 
+/// Error returned by `try_read`
 #[derive(Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum TryReadError {
@@ -110,6 +119,7 @@ pub enum TryReadError {
     Empty,
 }
 
+/// Error returned by `try_write`
 #[derive(Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum TryWriteError {
@@ -177,6 +187,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 +205,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 +234,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> {
@@ -288,7 +305,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 +396,29 @@ 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 })
     }
 
+    /// Get mutable access to the lower-level driver from the `bxcan` crate.
     pub 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 +500,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 +508,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 +616,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;
-}
-
-pub trait RX0Instance {
+    /// RX0 interrupt for this instance.
     type RX0Interrupt: crate::interrupt::typelevel::Interrupt;
-}
-
-pub trait RX1Instance {
+    /// RX1 interrupt for this instance.
     type RX1Interrupt: crate::interrupt::typelevel::Interrupt;
-}
-
-pub trait SCEInstance {
+    /// SCE interrupt for this instance.
     type SCEInterrupt: crate::interrupt::typelevel::Interrupt;
 }
 
-pub trait InterruptableInstance: TXInstance + RX0Instance + RX1Instance + SCEInstance {}
-pub trait Instance: sealed::Instance + RccPeripheral + InterruptableInstance + 'static {}
-
+/// BXCAN instance newtype.
 pub struct BxcanInstance<'a, T>(PeripheralRef<'a, T>);
 
 unsafe impl<'d, T: Instance> bxcan::Instance for BxcanInstance<'d, T> {
@@ -620,8 +645,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 {
-                &crate::pac::$inst
+            fn regs() -> crate::pac::can::Can {
+                crate::pac::$inst
             }
 
             fn state() -> &'static sealed::State {
@@ -630,33 +655,13 @@ foreach_peripheral!(
             }
         }
 
-        impl Instance for peripherals::$inst {}
-
-        foreach_interrupt!(
-            ($inst,can,CAN,TX,$irq:ident) => {
-                impl TXInstance for peripherals::$inst {
-                    type TXInterrupt = crate::interrupt::typelevel::$irq;
+        impl Instance for peripherals::$inst {
+            type TXInterrupt = crate::_generated::peripheral_interrupts::$inst::TX;
+            type RX0Interrupt = crate::_generated::peripheral_interrupts::$inst::RX0;
+            type RX1Interrupt = crate::_generated::peripheral_interrupts::$inst::RX1;
+            type SCEInterrupt = crate::_generated::peripheral_interrupts::$inst::SCE;
         }
     };
-            ($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 {}
-    };
 );
 
 foreach_peripheral!(

embassy-stm32/src/can/mod.rs

@@ -1,3 +1,4 @@
+//! Controller Area Network (CAN)
 #![macro_use]
 
 #[cfg_attr(can_bxcan, path = "bxcan.rs")]

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")]

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()
     }

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;

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;

embassy-stm32/src/dma/mod.rs

@@ -1,3 +1,5 @@
+//! Direct Memory Access (DMA)
+
 #[cfg(dma)]
 pub(crate) mod dma;
 #[cfg(dma)]

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")]

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,

embassy-stm32/src/exti.rs

@@ -1,3 +1,4 @@
+//! External Interrupts (EXTI)
 use core::convert::Infallible;
 use core::future::Future;
 use core::marker::PhantomData;

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 }
     }
@@ -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 }

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;

embassy-stm32/src/flash/mod.rs

@@ -1,3 +1,4 @@
+//! Flash memory (FLASH)
 use embedded_storage::nor_flash::{NorFlashError, NorFlashErrorKind};
 
 #[cfg(flash_f4)]

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!(

embassy-stm32/src/gpio.rs

@@ -1,3 +1,5 @@
+//! General-purpose Input/Output (GPIO)
+
 #![macro_use]
 use core::convert::Infallible;
 

embassy-stm32/src/hrtim/mod.rs

@@ -1,3 +1,5 @@
+//! High Resolution Timer (HRTIM)
+
 mod traits;
 
 use core::marker::PhantomData;

embassy-stm32/src/i2c/mod.rs

@@ -1,17 +1,24 @@
+//! 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 embassy_sync::waitqueue::AtomicWaker;
 
-use crate::peripherals;
+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::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)]
@@ -33,6 +40,148 @@ pub enum Error {
     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 {
+    #[cfg(not(feature = "time"))]
+    #[inline]
+    fn check(self) -> Result<(), Error> {
+        Ok(())
+    }
+
+    #[cfg(feature = "time")]
+    #[inline]
+    fn check(self) -> Result<(), Error> {
+        if Instant::now() > self.deadline {
+            Err(Error::Timeout)
+        } else {
+            Ok(())
+        }
+    }
+
+    #[cfg(not(feature = "time"))]
+    #[inline]
+    fn with<R>(self, fut: impl Future<Output = Result<R, Error>>) -> impl Future<Output = Result<R, Error>> {
+        fut
+    }
+
+    #[cfg(feature = "time")]
+    #[inline]
+    fn with<R>(self, fut: impl Future<Output = Result<R, Error>>) -> impl Future<Output = Result<R, Error>> {
+        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,
+        })
+    }
+}
+
 pub(crate) mod sealed {
     use super::*;
 

embassy-stm32/src/i2c/v1.rs

@@ -1,20 +1,14 @@
 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::gpio::sealed::AFType;
-use crate::gpio::Pull;
-use crate::interrupt::typelevel::Interrupt;
+use crate::dma::Transfer;
 use crate::pac::i2c;
 use crate::time::Hertz;
-use crate::{interrupt, Peripheral};
 
 pub unsafe fn on_interrupt<T: Instance>() {
     let regs = T::regs();
@@ -30,55 +24,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(
-        _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,
-            },
-        );
-
+    pub(crate) fn init(&mut self, freq: Hertz, _config: Config) {
         T::regs().cr1().modify(|reg| {
             reg.set_pe(false);
             //reg.set_anfoff(false);
@@ -101,15 +48,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 +107,7 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
         Ok(sr1)
     }
 
-    fn write_bytes(
-        &mut self,
-        addr: u8,
-        bytes: &[u8],
-        check_timeout: impl Fn() -> Result<(), Error>,
-    ) -> Result<(), Error> {
+    fn write_bytes(&mut self, addr: u8, bytes: &[u8], timeout: Timeout) -> Result<(), Error> {
         // Send a START condition
 
         T::regs().cr1().modify(|reg| {
@@ -183,7 +116,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 +126,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 +136,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 +144,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 +168,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(
-        &mut self,
-        addr: u8,
-        buffer: &mut [u8],
-        check_timeout: impl Fn() -> Result<(), Error>,
-    ) -> Result<(), Error> {
+    fn blocking_read_timeout(&mut self, addr: u8, buffer: &mut [u8], timeout: Timeout) -> 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 +198,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 +206,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 +215,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 +223,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 +233,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 +247,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(
-        &mut self,
-        addr: u8,
-        write: &[u8],
-        check_timeout: impl Fn() -> Result<(), Error>,
-    ) -> Result<(), Error> {
-        self.write_bytes(addr, write, &check_timeout)?;
+    /// Blocking write.
+    pub fn blocking_write(&mut self, addr: u8, write: &[u8]) -> Result<(), Error> {
+        let timeout = self.timeout();
+
+        self.write_bytes(addr, write, 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> {
-        self.blocking_write_timeout(addr, write, || Ok(()))
-    }
+    /// Blocking write, restart, read.
+    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(
-        &mut self,
-        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)?;
+        self.write_bytes(addr, write, timeout)?;
+        self.blocking_read_timeout(addr, read, 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
@@ -522,6 +438,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 +461,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 +621,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>,

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::gpio::sealed::AFType;
-use crate::gpio::Pull;
-use crate::interrupt::typelevel::Interrupt;
+use crate::dma::Transfer;
 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(
-        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,
-            },
-        );
-
+    pub(crate) fn init(&mut self, freq: Hertz, _config: Config) {
         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(
-        address: u8,
-        length: usize,
-        stop: Stop,
-        reload: bool,
-        check_timeout: impl Fn() -> Result<(), Error>,
-    ) -> Result<(), Error> {
+    fn master_write(address: u8, length: usize, stop: Stop, reload: bool, timeout: Timeout) -> 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(
-        length: usize,
-        reload: bool,
-        check_timeout: impl Fn() -> Result<(), Error>,
-    ) -> Result<(), Error> {
+    fn master_continue(length: usize, reload: bool, timeout: Timeout) -> 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(
-        &mut self,
-        address: u8,
-        read: &mut [u8],
-        restart: bool,
-        check_timeout: impl Fn() -> Result<(), Error>,
-    ) -> Result<(), Error> {
+    fn read_internal(&mut self, address: u8, read: &mut [u8], restart: bool, timeout: Timeout) -> 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(
-        &mut self,
-        address: u8,
-        write: &[u8],
-        send_stop: bool,
-        check_timeout: impl Fn() -> Result<(), Error>,
-    ) -> Result<(), Error> {
+    fn write_internal(&mut self, address: u8, write: &[u8], send_stop: bool, timeout: Timeout) -> 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,41 +473,31 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
 
     // =========================
     //  Async public API
-    #[cfg(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, timeout_fn(self.timeout))
+            self.write_internal(address, write, true, 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"))]
-    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, no_timeout_fn())
-        } 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>,
     {
+        let timeout = self.timeout();
+
         if write.is_empty() {
             return Err(Error::ZeroLengthTransfer);
         }
@@ -638,123 +509,49 @@ impl<'d, T: Instance, TXDMA, RXDMA> I2c<'d, T, TXDMA, RXDMA> {
             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))?;
+            let fut = self.write_dma_internal(address, c, first, is_last, timeout);
+            timeout.with(fut).await?;
             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);
-        }
-        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();
-
-            self.write_dma_internal(address, c, first, is_last, no_timeout_fn())
-                .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>,
     {
+        let timeout = self.timeout();
+
         if buffer.is_empty() {
-            self.read_internal(address, buffer, false, timeout_fn(self.timeout))
+            self.read_internal(address, buffer, false, 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))
+            let fut = self.read_dma_internal(address, buffer, false, timeout);
+            timeout.with(fut).await
         }
     }
 
-    #[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())
-        } else {
-            self.read_dma_internal(address, buffer, false, no_timeout_fn()).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 check_timeout = timeout_fn(self.timeout);
+        let timeout = self.timeout();
+
         if write.is_empty() {
-            self.write_internal(address, write, false, &check_timeout)?;
+            self.write_internal(address, write, false, 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)?;
-        } 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")]
-    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")]
+    /// Blocking read.
     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(()))
-    }
-
-    #[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)
+        self.read_internal(address, read, false, self.timeout())
         // Automatic Stop
     }
 
-    #[cfg(not(feature = "time"))]
-    pub fn blocking_write_read_timeout(
-        &mut self,
-        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)
+    /// Blocking write.
+    pub fn blocking_write(&mut self, address: u8, write: &[u8]) -> Result<(), Error> {
+        self.write_internal(address, write, true, self.timeout())
+    }
+
+    /// Blocking write, restart, read.
+    pub fn blocking_write_read(&mut self, address: u8, write: &[u8], read: &mut [u8]) -> Result<(), Error> {
+        let timeout = self.timeout();
+        self.write_internal(address, write, false, timeout)?;
+        self.read_internal(address, read, true, 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"))]
-    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(()))
-    }
-
-    fn blocking_write_vectored_with_timeout(
-        &mut self,
-        address: u8,
-        write: &[&[u8]],
-        check_timeout: impl Fn() -> Result<(), Error>,
-    ) -> Result<(), Error> {
+    /// Blocking write multiple buffers.
+    ///
+    /// The buffers are concatenated in a single write transaction.
+    pub fn blocking_write_vectored(&mut self, address: u8, write: &[&[u8]]) -> 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> {

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>,

embassy-stm32/src/lib.rs

@@ -149,15 +149,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,7 +196,11 @@ 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);

embassy-stm32/src/qspi/mod.rs

@@ -1,3 +1,5 @@
+//! Quad Serial Peripheral Interface (QSPI)
+
 #![macro_use]
 
 pub mod enums;

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;
 

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| {
@@ -106,7 +116,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 +128,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 +229,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;
 }
 

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 {

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;
@@ -102,7 +102,7 @@ pub enum RtcError {
     NotRunning,
 }
 
-pub struct RtcTimeProvider {
+pub(crate) struct RtcTimeProvider {
     _private: (),
 }
 
@@ -127,7 +127,7 @@ 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;
@@ -163,7 +163,7 @@ impl RtcTimeProvider {
     }
 }
 
-/// RTC Abstraction
+/// RTC driver.
 pub struct Rtc {
     #[cfg(feature = "low-power")]
     stop_time: Mutex<CriticalSectionRawMutex, Cell<Option<RtcInstant>>>,
@@ -171,6 +171,7 @@ pub struct Rtc {
     _private: (),
 }
 
+/// RTC configuration.
 #[non_exhaustive]
 #[derive(Copy, Clone, PartialEq)]
 pub struct RtcConfig {
@@ -188,6 +189,7 @@ impl Default for RtcConfig {
     }
 }
 
+/// Calibration cycle period.
 #[derive(Copy, Clone, Debug, PartialEq)]
 #[repr(u8)]
 pub enum RtcCalibrationCyclePeriod {
@@ -206,6 +208,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();
@@ -240,7 +243,7 @@ impl Rtc {
     }
 
     /// Acquire a [`RtcTimeProvider`] instance.
-    pub const fn time_provider(&self) -> RtcTimeProvider {
+    pub(crate) const fn time_provider(&self) -> RtcTimeProvider {
         RtcTimeProvider { _private: () }
     }
 
@@ -315,6 +318,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.

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 {
-    None,
-    Sai1BlockA,
-    Sai1BlockB,
-    Sai2BlockA,
-    Sai2BlockB,
-}
-
-#[derive(Copy, Clone)]
-pub enum SyncIn {
-    None,
-    ChannelZero,
-    ChannelOne,
-}
-
-#[derive(Copy, Clone)]
+#[allow(missing_docs)]
 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 {
-    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)]
+#[allow(missing_docs)]
 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 {
-    NoError,
-    OverUnderRunDetected,
-}
-
-#[derive(Copy, Clone)]
+#[allow(missing_docs)]
 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) {
     (
@@ -591,34 +550,6 @@ fn get_ring_buffer<'d, T: Instance, C: Channel, W: word::Word>(
     }
 }
 
-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,19 +567,58 @@ fn update_synchronous_config(config: &mut Config) {
     }
 }
 
-impl SubBlockA {
-    pub fn new_asynchronous_with_mclk<'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,
-        mclk: impl Peripheral<P = impl MclkAPin<T>> + 'd,
+/// SAI subblock instance.
+pub struct SubBlock<'d, T, S: SubBlockInstance> {
+    peri: PeripheralRef<'d, T>,
+    _phantom: PhantomData<S>,
+}
+
+/// Split the main SAIx peripheral into the two subblocks.
+///
+/// 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 {
+            peri: unsafe { peri.clone_unchecked() },
+            _phantom: PhantomData,
+        },
+        SubBlock {
+            peri,
+            _phantom: PhantomData,
+        },
+    )
+}
+
+/// SAI sub-block driver.
+pub struct Sai<'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,
+}
+
+impl<'d, T: Instance, C: Channel, W: word::Word> Sai<'d, T, C, W> {
+    /// Create a new SAI driver in asynchronous mode with MCLK.
+    ///
+    /// You can obtain the [`SubBlock`] with [`split_subblocks`].
+    pub fn new_asynchronous_with_mclk<S: SubBlockInstance>(
+        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,
+        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 + DmaA<T>,
+        C: Channel + Dma<T, S>,
     {
         into_ref!(mclk);
 
@@ -664,19 +634,22 @@ impl SubBlockA {
         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,
+    /// Create a new SAI driver in asynchronous mode without MCLK.
+    ///
+    /// You can obtain the [`SubBlock`] with [`split_subblocks`].
+    pub fn new_asynchronous<S: SubBlockInstance>(
+        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 + DmaA<T>,
+        C: Channel + Dma<T, S>,
     {
-        let peri = peri.0;
+        let peri = peri.peri;
         into_ref!(peri, dma, sck, sd, fs);
 
         let (sd_af_type, ck_af_type) = get_af_types(config.mode, config.tx_rx);
@@ -688,10 +661,10 @@ impl SubBlockA {
         fs.set_as_af(fs.af_num(), ck_af_type);
         fs.set_speed(crate::gpio::Speed::VeryHigh);
 
-        let sub_block = WhichSubBlock::A;
+        let sub_block = S::WHICH;
         let request = dma.request();
 
-        SubBlock::new_inner(
+        Self::new_inner(
             peri,
             sub_block,
             Some(sck.map_into()),
@@ -703,19 +676,22 @@ impl SubBlockA {
         )
     }
 
-    pub fn new_synchronous<'d, T: Instance, C: Channel, W: word::Word>(
-        peri: SubBlockAPeripheral<'d, T>,
-        sd: impl Peripheral<P = impl SdAPin<T>> + 'd,
+    /// Create a new SAI driver in synchronous mode.
+    ///
+    /// 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 + DmaA<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);
@@ -723,10 +699,10 @@ impl SubBlockA {
         sd.set_as_af(sd.af_num(), sd_af_type);
         sd.set_speed(crate::gpio::Speed::VeryHigh);
 
-        let sub_block = WhichSubBlock::A;
+        let sub_block = S::WHICH;
         let request = dma.request();
 
-        SubBlock::new_inner(
+        Self::new_inner(
             peri,
             sub_block,
             None,
@@ -737,129 +713,6 @@ impl SubBlockA {
             config,
         )
     }
-}
-
-impl SubBlockB {
-    pub fn new_asynchronous_with_mclk<'d, T: Instance, C: Channel, W: word::Word>(
-        peri: SubBlockBPeripheral<'d, T>,
-        sck: impl Peripheral<P = impl SckBPin<T>> + 'd,
-        sd: impl Peripheral<P = impl SdBPin<T>> + 'd,
-        fs: impl Peripheral<P = impl FsBPin<T>> + 'd,
-        mclk: impl Peripheral<P = impl MclkBPin<T>> + 'd,
-        dma: impl Peripheral<P = C> + 'd,
-        dma_buf: &'d mut [W],
-        mut config: Config,
-    ) -> SubBlock<'d, T, C, W>
-    where
-        C: Channel + DmaB<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: SubBlockBPeripheral<'d, T>,
-        sck: impl Peripheral<P = impl SckBPin<T>> + 'd,
-        sd: impl Peripheral<P = impl SdBPin<T>> + 'd,
-        fs: impl Peripheral<P = impl FsBPin<T>> + 'd,
-        dma: impl Peripheral<P = C> + 'd,
-        dma_buf: &'d mut [W],
-        config: Config,
-    ) -> SubBlock<'d, T, C, W>
-    where
-        C: Channel + DmaB<T>,
-    {
-        let peri = peri.0;
-        into_ref!(dma, peri, 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::B;
-        let request = dma.request();
-
-        SubBlock::new_inner(
-            peri,
-            sub_block,
-            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: SubBlockBPeripheral<'d, T>,
-        sd: impl Peripheral<P = impl SdBPin<T>> + 'd,
-        dma: impl Peripheral<P = C> + 'd,
-        dma_buf: &'d mut [W],
-        mut config: Config,
-    ) -> SubBlock<'d, T, C, W>
-    where
-        C: Channel + DmaB<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::B;
-        let request = dma.request();
-
-        SubBlock::new_inner(
-            peri,
-            sub_block,
-            None,
-            None,
-            Some(sd.map_into()),
-            None,
-            get_ring_buffer::<T, C, W>(dma, dma_buf, request, sub_block, config.tx_rx),
-            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)]
-    /// Reconfigures it with the supplied config.
-    fn reconfigure(&mut self, _config: Config) {}
-
-    pub fn get_current_config(&self) -> Config {
-        Config::default()
-    }
-
+    /// Write data to the SAI ringbuffer.
+    ///
+    /// This appends the data to the buffer and returns immediately. The
+    /// data will be transmitted in the background.
+    ///
+    /// 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 Word: word::Word {}
+    pub trait SubBlock {
+        const WHICH: WhichSubBlock;
+    }
+}
 
+/// 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!(SckBPin, Instance);
-pin_trait!(FsAPin, Instance);
-pin_trait!(FsBPin, Instance);
-pin_trait!(SdAPin, Instance);
-pin_trait!(SdBPin, Instance);
-pin_trait!(MclkAPin, Instance);
-pin_trait!(MclkBPin, Instance);
+pin_trait!(SckPin, Instance, SubBlockInstance);
+pin_trait!(FsPin, Instance, SubBlockInstance);
+pin_trait!(SdPin, Instance, SubBlockInstance);
+pin_trait!(MclkPin, Instance, SubBlockInstance);
 
-dma_trait!(DmaA, Instance);
-dma_trait!(DmaB, Instance);
+dma_trait!(Dma, Instance, SubBlockInstance);
 
 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(())
-    }
-}

embassy-stm32/src/sdmmc/mod.rs

@@ -1,3 +1,4 @@
+//! Secure Digital / MultiMedia Card (SDMMC)
 #![macro_use]
 
 use core::default::Default;

embassy-stm32/src/spi/mod.rs

@@ -1,3 +1,4 @@
+//! Serial Peripheral Interface (SPI)
 #![macro_use]
 
 use core::ptr;

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};

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,6 +10,7 @@ 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::*;

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};

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};

embassy-stm32/src/traits.rs

@@ -1,9 +1,9 @@
 #![macro_use]
 
 macro_rules! pin_trait {
-    ($signal:ident, $instance:path) => {
+    ($signal:ident, $instance:path $(, $mode:path)?) => {
         #[doc = concat!(stringify!($signal), " pin trait")]
-        pub trait $signal<T: $instance>: crate::gpio::Pin {
+        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;
         }
@@ -11,8 +11,8 @@ macro_rules! pin_trait {
 }
 
 macro_rules! pin_trait_impl {
-    (crate::$mod:ident::$trait:ident, $instance:ident, $pin:ident, $af:expr) => {
-        impl crate::$mod::$trait<crate::peripherals::$instance> for crate::peripherals::$pin {
+    (crate::$mod:ident::$trait:ident$(<$mode:ident>)?, $instance:ident, $pin:ident, $af:expr) => {
+        impl crate::$mod::$trait<crate::peripherals::$instance $(, crate::$mod::$mode)?> for crate::peripherals::$pin {
             fn af_num(&self) -> u8 {
                 $af
             }
@@ -23,9 +23,9 @@ macro_rules! pin_trait_impl {
 // ====================
 
 macro_rules! dma_trait {
-    ($signal:ident, $instance:path) => {
+    ($signal:ident, $instance:path$(, $mode:path)?) => {
         #[doc = concat!(stringify!($signal), " DMA request trait")]
-        pub trait $signal<T: $instance>: crate::dma::Channel {
+        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.
@@ -37,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) => {
-        impl<T> crate::$mod::$trait<crate::peripherals::$instance> for T
+    (crate::$mod:ident::$trait:ident$(<$mode:ident>)?, $instance:ident, {dmamux: $dmamux:ident}, $request:expr) => {
+        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>,
         {
@@ -49,8 +49,8 @@ macro_rules! dma_trait_impl {
     };
 
     // DMAMUX
-    (crate::$mod:ident::$trait:ident, $instance:ident, {dma: $dma:ident}, $request:expr) => {
-        impl<T> crate::$mod::$trait<crate::peripherals::$instance> for T
+    (crate::$mod:ident::$trait:ident$(<$mode:ident>)?, $instance:ident, {dma: $dma:ident}, $request:expr) => {
+        impl<T> crate::$mod::$trait<crate::peripherals::$instance $(, crate::$mod::$mode)?> for T
         where
             T: crate::dma::Channel,
         {
@@ -61,8 +61,8 @@ macro_rules! dma_trait_impl {
     };
 
     // DMA/GPDMA, without DMAMUX
-    (crate::$mod:ident::$trait:ident, $instance:ident, {channel: $channel:ident}, $request:expr) => {
-        impl crate::$mod::$trait<crate::peripherals::$instance> for crate::peripherals::$channel {
+    (crate::$mod:ident::$trait:ident$(<$mode:ident>)?, $instance:ident, {channel: $channel:ident}, $request:expr) => {
+        impl crate::$mod::$trait<crate::peripherals::$instance $(, crate::$mod::$mode)?> for crate::peripherals::$channel {
             fn request(&self) -> crate::dma::Request {
                 $request
             }

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]>() }

embassy-stm32/src/usart/mod.rs

@@ -1,3 +1,4 @@
+//! Universal Synchronous/Asynchronous Receiver Transmitter (USART, UART, LPUART)
 #![macro_use]
 
 use core::future::poll_fn;

embassy-stm32/src/usb_otg/mod.rs

@@ -1,3 +1,5 @@
+//! USB On The Go (OTG)
+
 use crate::rcc::RccPeripheral;
 use crate::{interrupt, peripherals};
 

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};