Merge remote-tracking branch 'origin/main' into james/read_to_break

ci.sh

@@ -91,12 +91,12 @@ cargo batch  \
     --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f417zg,defmt,exti,time-driver-any,time \
     --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f423zh,defmt,exti,time-driver-any,time \
     --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f427zi,defmt,exti,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f429zi,log,exti,time-driver-any,embedded-sdmmc,time \
+    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f429zi,log,exti,time-driver-any,time \
     --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f437zi,log,exti,time-driver-any,time \
     --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f439zi,defmt,exti,time-driver-any,time \
     --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f446ze,defmt,exti,time-driver-any,time \
     --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f469zi,defmt,exti,time-driver-any,time \
-    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f479zi,defmt,exti,time-driver-any,embedded-sdmmc,time \
+    --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f479zi,defmt,exti,time-driver-any,time \
     --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32f730i8,defmt,exti,time-driver-any,time \
     --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32h753zi,defmt,exti,time-driver-any,time \
     --- build --release --manifest-path embassy-stm32/Cargo.toml --target thumbv7em-none-eabi --features stm32h735zg,defmt,exti,time-driver-any,time \

cyw43-pio/README.md

@@ -0,0 +1,17 @@
+# cyw43-pio
+
+RP2040 PIO driver for the nonstandard half-duplex SPI used in the Pico W. The PIO driver offloads SPI communication with the WiFi chip and improves throughput.
+
+## 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.

cyw43-pio/src/lib.rs

@@ -1,16 +1,19 @@
 #![no_std]
 #![allow(async_fn_in_trait)]
+#![doc = include_str!("../README.md")]
+#![warn(missing_docs)]
 
 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, Common, Config, Direction, Instance, Irq, PioPin, ShiftDirection, StateMachine};
-use embassy_rp::{pio_instr_util, Peripheral, PeripheralRef};
+use embassy_rp::{Peripheral, PeripheralRef};
 use fixed::FixedU32;
 use pio_proc::pio_asm;
 
+/// SPI comms driven by PIO.
 pub struct PioSpi<'d, CS: Pin, PIO: Instance, const SM: usize, DMA> {
     cs: Output<'d, CS>,
     sm: StateMachine<'d, PIO, SM>,
@@ -25,6 +28,7 @@ where
     CS: Pin,
     PIO: Instance,
 {
+    /// Create a new instance of PioSpi.
     pub fn new<DIO, CLK>(
         common: &mut Common<'d, PIO>,
         mut sm: StateMachine<'d, PIO, SM>,
@@ -143,6 +147,7 @@ where
         }
     }
 
+    /// Write data to peripheral and return status.
     pub async fn write(&mut self, write: &[u32]) -> u32 {
         self.sm.set_enable(false);
         let write_bits = write.len() * 32 - 1;
@@ -152,10 +157,10 @@ where
         defmt::trace!("write={} read={}", write_bits, read_bits);
 
         unsafe {
-            pio_instr_util::set_x(&mut self.sm, write_bits as u32);
+            instr::set_x(&mut self.sm, write_bits as u32);
-            pio_instr_util::set_y(&mut self.sm, read_bits as u32);
+            instr::set_y(&mut self.sm, read_bits as u32);
-            pio_instr_util::set_pindir(&mut self.sm, 0b1);
+            instr::set_pindir(&mut self.sm, 0b1);
-            pio_instr_util::exec_jmp(&mut self.sm, self.wrap_target);
+            instr::exec_jmp(&mut self.sm, self.wrap_target);
         }
 
         self.sm.set_enable(true);
@@ -170,6 +175,7 @@ where
         status
     }
 
+    /// Send command and read response into buffer.
     pub async fn cmd_read(&mut self, cmd: u32, read: &mut [u32]) -> u32 {
         self.sm.set_enable(false);
         let write_bits = 31;
@@ -179,10 +185,10 @@ where
         defmt::trace!("write={} read={}", write_bits, read_bits);
 
         unsafe {
-            pio_instr_util::set_y(&mut self.sm, read_bits as u32);
+            instr::set_y(&mut self.sm, read_bits as u32);
-            pio_instr_util::set_x(&mut self.sm, write_bits as u32);
+            instr::set_x(&mut self.sm, write_bits as u32);
-            pio_instr_util::set_pindir(&mut self.sm, 0b1);
+            instr::set_pindir(&mut self.sm, 0b1);
-            pio_instr_util::exec_jmp(&mut self.sm, self.wrap_target);
+            instr::exec_jmp(&mut self.sm, self.wrap_target);
         }
 
         // self.cs.set_low();

cyw43/README.md

@@ -45,6 +45,10 @@ nc 192.168.0.250 1234
 ```
 Send it some data, you should see it echoed back and printed in the firmware's logs.
 
+## 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

cyw43/src/control.rs

@@ -12,17 +12,23 @@ use crate::ioctl::{IoctlState, IoctlType};
 use crate::structs::*;
 use crate::{countries, events, PowerManagementMode};
 
+/// Control errors.
 #[derive(Debug)]
 pub struct Error {
+    /// Status code.
     pub status: u32,
 }
 
+/// Multicast errors.
 #[derive(Debug)]
 pub enum AddMulticastAddressError {
+    /// Not a multicast address.
     NotMulticast,
+    /// No free address slots.
     NoFreeSlots,
 }
 
+/// Control driver.
 pub struct Control<'a> {
     state_ch: ch::StateRunner<'a>,
     events: &'a Events,
@@ -38,6 +44,7 @@ impl<'a> Control<'a> {
         }
     }
 
+    /// Initialize WiFi controller.
     pub async fn init(&mut self, clm: &[u8]) {
         const CHUNK_SIZE: usize = 1024;
 
@@ -154,6 +161,7 @@ impl<'a> Control<'a> {
         self.ioctl(IoctlType::Set, IOCTL_CMD_DOWN, 0, &mut []).await;
     }
 
+    /// Set power management mode.
     pub async fn set_power_management(&mut self, mode: PowerManagementMode) {
         // power save mode
         let mode_num = mode.mode();
@@ -166,6 +174,7 @@ impl<'a> Control<'a> {
         self.ioctl_set_u32(86, 0, mode_num).await;
     }
 
+    /// Join an unprotected network with the provided ssid.
     pub async fn join_open(&mut self, ssid: &str) -> Result<(), Error> {
         self.set_iovar_u32("ampdu_ba_wsize", 8).await;
 
@@ -183,6 +192,7 @@ impl<'a> Control<'a> {
         self.wait_for_join(i).await
     }
 
+    /// Join an protected network with the provided ssid and passphrase.
     pub async fn join_wpa2(&mut self, ssid: &str, passphrase: &str) -> Result<(), Error> {
         self.set_iovar_u32("ampdu_ba_wsize", 8).await;
 
@@ -250,16 +260,19 @@ impl<'a> Control<'a> {
         }
     }
 
+    /// Set GPIO pin on WiFi chip.
     pub async fn gpio_set(&mut self, gpio_n: u8, gpio_en: bool) {
         assert!(gpio_n < 3);
         self.set_iovar_u32x2("gpioout", 1 << gpio_n, if gpio_en { 1 << gpio_n } else { 0 })
             .await
     }
 
+    /// Start open access point.
     pub async fn start_ap_open(&mut self, ssid: &str, channel: u8) {
         self.start_ap(ssid, "", Security::OPEN, channel).await;
     }
 
+    /// Start WPA2 protected access point.
     pub async fn start_ap_wpa2(&mut self, ssid: &str, passphrase: &str, channel: u8) {
         self.start_ap(ssid, passphrase, Security::WPA2_AES_PSK, channel).await;
     }
@@ -494,13 +507,14 @@ impl<'a> Control<'a> {
     }
 }
 
+/// WiFi network scanner.
 pub struct Scanner<'a> {
     subscriber: EventSubscriber<'a>,
     events: &'a Events,
 }
 
 impl Scanner<'_> {
-    /// wait for the next found network
+    /// Wait for the next found network.
     pub async fn next(&mut self) -> Option<BssInfo> {
         let event = self.subscriber.next_message_pure().await;
         if event.header.status != EStatus::PARTIAL {

cyw43/src/lib.rs

@@ -2,6 +2,8 @@
 #![no_main]
 #![allow(async_fn_in_trait)]
 #![deny(unused_must_use)]
+#![doc = include_str!("../README.md")]
+#![warn(missing_docs)]
 
 // This mod MUST go first, so that the others see its macros.
 pub(crate) mod fmt;
@@ -102,6 +104,7 @@ const CHIP: Chip = Chip {
     chanspec_ctl_sb_mask: 0x0700,
 };
 
+/// Driver state.
 pub struct State {
     ioctl_state: IoctlState,
     ch: ch::State<MTU, 4, 4>,
@@ -109,6 +112,7 @@ pub struct State {
 }
 
 impl State {
+    /// Create new driver state holder.
     pub fn new() -> Self {
         Self {
             ioctl_state: IoctlState::new(),
@@ -118,6 +122,7 @@ impl State {
     }
 }
 
+/// Power management modes.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum PowerManagementMode {
     /// Custom, officially unsupported mode. Use at your own risk.
@@ -203,8 +208,13 @@ impl PowerManagementMode {
     }
 }
 
+/// Embassy-net driver.
 pub type NetDriver<'a> = ch::Device<'a, MTU>;
 
+/// Create a new instance of the CYW43 driver.
+///
+/// Returns a handle to the network device, control handle and a runner for driving the low level
+/// stack.
 pub async fn new<'a, PWR, SPI>(
     state: &'a mut State,
     pwr: PWR,

cyw43/src/runner.rs

@@ -34,6 +34,7 @@ impl Default for LogState {
     }
 }
 
+/// Driver communicating with the WiFi chip.
 pub struct Runner<'a, PWR, SPI> {
     ch: ch::Runner<'a, MTU>,
     bus: Bus<PWR, SPI>,
@@ -222,6 +223,7 @@ where
         }
     }
 
+    /// Run the
     pub async fn run(mut self) -> ! {
         let mut buf = [0; 512];
         loop {

cyw43/src/structs.rs

@@ -4,13 +4,16 @@ use crate::fmt::Bytes;
 macro_rules! impl_bytes {
     ($t:ident) => {
         impl $t {
+            /// Bytes consumed by this type.
             pub const SIZE: usize = core::mem::size_of::<Self>();
 
+            /// Convert to byte array.
             #[allow(unused)]
             pub fn to_bytes(&self) -> [u8; Self::SIZE] {
                 unsafe { core::mem::transmute(*self) }
             }
 
+            /// Create from byte array.
             #[allow(unused)]
             pub fn from_bytes(bytes: &[u8; Self::SIZE]) -> &Self {
                 let alignment = core::mem::align_of::<Self>();
@@ -23,6 +26,7 @@ macro_rules! impl_bytes {
                 unsafe { core::mem::transmute(bytes) }
             }
 
+            /// Create from mutable byte array.
             #[allow(unused)]
             pub fn from_bytes_mut(bytes: &mut [u8; Self::SIZE]) -> &mut Self {
                 let alignment = core::mem::align_of::<Self>();
@@ -204,6 +208,7 @@ pub struct EthernetHeader {
 }
 
 impl EthernetHeader {
+    /// Swap endianness.
     pub fn byteswap(&mut self) {
         self.ether_type = self.ether_type.to_be();
     }
@@ -472,19 +477,26 @@ impl ScanResults {
 #[repr(C, packed(2))]
 #[non_exhaustive]
 pub struct BssInfo {
+    /// Version.
     pub version: u32,
+    /// Length.
     pub length: u32,
+    /// BSSID.
     pub bssid: [u8; 6],
+    /// Beacon period.
     pub beacon_period: u16,
+    /// Capability.
     pub capability: u16,
+    /// SSID length.
     pub ssid_len: u8,
+    /// SSID.
     pub ssid: [u8; 32],
     // there will be more stuff here
 }
 impl_bytes!(BssInfo);
 
 impl BssInfo {
-    pub fn parse(packet: &mut [u8]) -> Option<&mut Self> {
+    pub(crate) fn parse(packet: &mut [u8]) -> Option<&mut Self> {
         if packet.len() < BssInfo::SIZE {
             return None;
         }

embassy-boot/boot/Cargo.toml

@@ -26,25 +26,22 @@ features = ["defmt"]
 defmt = { version = "0.3", optional = true }
 digest = "0.10"
 log = { version = "0.4", optional = true }
-ed25519-dalek = { version = "1.0.1", default_features = false, features = ["u32_backend"], optional = true }
+ed25519-dalek = { version = "2", default_features = false, features = ["digest"], optional = true }
 embassy-embedded-hal = { version = "0.1.0", path = "../../embassy-embedded-hal" }
 embassy-sync = { version = "0.5.0", path = "../../embassy-sync" }
 embedded-storage = "0.3.1"
 embedded-storage-async = { version = "0.4.1" }
-salty = { git = "https://github.com/ycrypto/salty.git", rev = "a9f17911a5024698406b75c0fac56ab5ccf6a8c7", optional = true }
+salty = { version = "0.3", optional = true }
-signature = { version = "1.6.4", default-features = false }
+signature = { version = "2.0", default-features = false }
 
 [dev-dependencies]
 log = "0.4"
 env_logger = "0.9"
-rand = "0.7" # ed25519-dalek v1.0.1 depends on this exact version
+rand = "0.8"
 futures = { version = "0.3", features = ["executor"] }
 sha1 = "0.10.5"
 critical-section = { version = "1.1.1", features = ["std"] }
-
+ed25519-dalek = { version = "2", default_features = false, features = ["std", "rand_core", "digest"]  }
-[dev-dependencies.ed25519-dalek]
-default_features = false
-features = ["rand", "std", "u32_backend"]
 
 [features]
 ed25519-dalek = ["dep:ed25519-dalek", "_verify"]

embassy-boot/boot/src/digest_adapters/ed25519_dalek.rs

@@ -1,6 +1,6 @@
 use digest::typenum::U64;
 use digest::{FixedOutput, HashMarker, OutputSizeUser, Update};
-use ed25519_dalek::Digest as _;
+use ed25519_dalek::Digest;
 
 pub struct Sha512(ed25519_dalek::Sha512);
 
@@ -12,7 +12,7 @@ impl Default for Sha512 {
 
 impl Update for Sha512 {
     fn update(&mut self, data: &[u8]) {
-        self.0.update(data)
+        Digest::update(&mut self.0, data)
     }
 }
 

embassy-boot/boot/src/firmware_updater/asynch.rs

@@ -79,8 +79,8 @@ impl<'d, DFU: NorFlash, STATE: NorFlash> FirmwareUpdater<'d, DFU, STATE> {
     #[cfg(feature = "_verify")]
     pub async fn verify_and_mark_updated(
         &mut self,
-        _public_key: &[u8],
+        _public_key: &[u8; 32],
-        _signature: &[u8],
+        _signature: &[u8; 64],
         _update_len: u32,
     ) -> Result<(), FirmwareUpdaterError> {
         assert!(_update_len <= self.dfu.capacity() as u32);
@@ -89,14 +89,14 @@ impl<'d, DFU: NorFlash, STATE: NorFlash> FirmwareUpdater<'d, DFU, STATE> {
 
         #[cfg(feature = "ed25519-dalek")]
         {
-            use ed25519_dalek::{PublicKey, Signature, SignatureError, Verifier};
+            use ed25519_dalek::{Signature, SignatureError, Verifier, VerifyingKey};
 
             use crate::digest_adapters::ed25519_dalek::Sha512;
 
             let into_signature_error = |e: SignatureError| FirmwareUpdaterError::Signature(e.into());
 
-            let public_key = PublicKey::from_bytes(_public_key).map_err(into_signature_error)?;
+            let public_key = VerifyingKey::from_bytes(_public_key).map_err(into_signature_error)?;
-            let signature = Signature::from_bytes(_signature).map_err(into_signature_error)?;
+            let signature = Signature::from_bytes(_signature);
 
             let mut chunk_buf = [0; 2];
             let mut message = [0; 64];
@@ -106,7 +106,6 @@ impl<'d, DFU: NorFlash, STATE: NorFlash> FirmwareUpdater<'d, DFU, STATE> {
         }
         #[cfg(feature = "ed25519-salty")]
         {
-            use salty::constants::{PUBLICKEY_SERIALIZED_LENGTH, SIGNATURE_SERIALIZED_LENGTH};
             use salty::{PublicKey, Signature};
 
             use crate::digest_adapters::salty::Sha512;
@@ -115,10 +114,8 @@ impl<'d, DFU: NorFlash, STATE: NorFlash> FirmwareUpdater<'d, DFU, STATE> {
                 FirmwareUpdaterError::Signature(signature::Error::default())
             }
 
-            let public_key: [u8; PUBLICKEY_SERIALIZED_LENGTH] = _public_key.try_into().map_err(into_signature_error)?;
+            let public_key = PublicKey::try_from(_public_key).map_err(into_signature_error)?;
-            let public_key = PublicKey::try_from(&public_key).map_err(into_signature_error)?;
+            let signature = Signature::try_from(_signature).map_err(into_signature_error)?;
-            let signature: [u8; SIGNATURE_SERIALIZED_LENGTH] = _signature.try_into().map_err(into_signature_error)?;
-            let signature = Signature::try_from(&signature).map_err(into_signature_error)?;
 
             let mut message = [0; 64];
             let mut chunk_buf = [0; 2];

embassy-boot/boot/src/firmware_updater/blocking.rs

@@ -86,8 +86,8 @@ impl<'d, DFU: NorFlash, STATE: NorFlash> BlockingFirmwareUpdater<'d, DFU, STATE>
     #[cfg(feature = "_verify")]
     pub fn verify_and_mark_updated(
         &mut self,
-        _public_key: &[u8],
+        _public_key: &[u8; 32],
-        _signature: &[u8],
+        _signature: &[u8; 64],
         _update_len: u32,
     ) -> Result<(), FirmwareUpdaterError> {
         assert!(_update_len <= self.dfu.capacity() as u32);
@@ -96,14 +96,14 @@ impl<'d, DFU: NorFlash, STATE: NorFlash> BlockingFirmwareUpdater<'d, DFU, STATE>
 
         #[cfg(feature = "ed25519-dalek")]
         {
-            use ed25519_dalek::{PublicKey, Signature, SignatureError, Verifier};
+            use ed25519_dalek::{Signature, SignatureError, Verifier, VerifyingKey};
 
             use crate::digest_adapters::ed25519_dalek::Sha512;
 
             let into_signature_error = |e: SignatureError| FirmwareUpdaterError::Signature(e.into());
 
-            let public_key = PublicKey::from_bytes(_public_key).map_err(into_signature_error)?;
+            let public_key = VerifyingKey::from_bytes(_public_key).map_err(into_signature_error)?;
-            let signature = Signature::from_bytes(_signature).map_err(into_signature_error)?;
+            let signature = Signature::from_bytes(_signature);
 
             let mut message = [0; 64];
             let mut chunk_buf = [0; 2];
@@ -113,7 +113,6 @@ impl<'d, DFU: NorFlash, STATE: NorFlash> BlockingFirmwareUpdater<'d, DFU, STATE>
         }
         #[cfg(feature = "ed25519-salty")]
         {
-            use salty::constants::{PUBLICKEY_SERIALIZED_LENGTH, SIGNATURE_SERIALIZED_LENGTH};
             use salty::{PublicKey, Signature};
 
             use crate::digest_adapters::salty::Sha512;
@@ -122,10 +121,8 @@ impl<'d, DFU: NorFlash, STATE: NorFlash> BlockingFirmwareUpdater<'d, DFU, STATE>
                 FirmwareUpdaterError::Signature(signature::Error::default())
             }
 
-            let public_key: [u8; PUBLICKEY_SERIALIZED_LENGTH] = _public_key.try_into().map_err(into_signature_error)?;
+            let public_key = PublicKey::try_from(_public_key).map_err(into_signature_error)?;
-            let public_key = PublicKey::try_from(&public_key).map_err(into_signature_error)?;
+            let signature = Signature::try_from(_signature).map_err(into_signature_error)?;
-            let signature: [u8; SIGNATURE_SERIALIZED_LENGTH] = _signature.try_into().map_err(into_signature_error)?;
-            let signature = Signature::try_from(&signature).map_err(into_signature_error)?;
 
             let mut message = [0; 64];
             let mut chunk_buf = [0; 2];

embassy-boot/boot/src/lib.rs

@@ -275,21 +275,19 @@ mod tests {
         // The following key setup is based on:
         // https://docs.rs/ed25519-dalek/latest/ed25519_dalek/#example
 
-        use ed25519_dalek::Keypair;
+        use ed25519_dalek::{Digest, Sha512, Signature, Signer, SigningKey, VerifyingKey};
         use rand::rngs::OsRng;
 
         let mut csprng = OsRng {};
-        let keypair: Keypair = Keypair::generate(&mut csprng);
+        let keypair = SigningKey::generate(&mut csprng);
 
-        use ed25519_dalek::{Digest, Sha512, Signature, Signer};
         let firmware: &[u8] = b"This are bytes that would otherwise be firmware bytes for DFU.";
         let mut digest = Sha512::new();
         digest.update(&firmware);
         let message = digest.finalize();
         let signature: Signature = keypair.sign(&message);
 
-        use ed25519_dalek::PublicKey;
+        let public_key = keypair.verifying_key();
-        let public_key: PublicKey = keypair.public;
 
         // Setup flash
         let flash = BlockingTestFlash::new(BootLoaderConfig {

embassy-boot/nrf/Cargo.toml

@@ -4,6 +4,12 @@ name = "embassy-boot-nrf"
 version = "0.1.0"
 description = "Bootloader lib for nRF chips"
 license = "MIT OR Apache-2.0"
+repository = "https://github.com/embassy-rs/embassy"
+categories = [
+    "embedded",
+    "no-std",
+    "asynchronous",
+]
 
 [package.metadata.embassy_docs]
 src_base = "https://github.com/embassy-rs/embassy/blob/embassy-boot-nrf-v$VERSION/embassy-boot/nrf/src/"
@@ -25,7 +31,7 @@ embedded-storage = "0.3.1"
 embedded-storage-async = { version = "0.4.1" }
 cfg-if = "1.0.0"
 
-nrf-softdevice-mbr = { version = "0.1.0", git = "https://github.com/embassy-rs/nrf-softdevice.git", branch = "master", optional = true }
+nrf-softdevice-mbr = { version = "0.2.0", optional = true }
 
 [features]
 defmt = [

embassy-boot/rp/Cargo.toml

@@ -4,6 +4,12 @@ name = "embassy-boot-rp"
 version = "0.1.0"
 description = "Bootloader lib for RP2040 chips"
 license = "MIT OR Apache-2.0"
+repository = "https://github.com/embassy-rs/embassy"
+categories = [
+    "embedded",
+    "no-std",
+    "asynchronous",
+]
 
 [package.metadata.embassy_docs]
 src_base = "https://github.com/embassy-rs/embassy/blob/embassy-boot-rp-v$VERSION/src/"

embassy-boot/stm32/Cargo.toml

@@ -4,6 +4,12 @@ name = "embassy-boot-stm32"
 version = "0.1.0"
 description = "Bootloader lib for STM32 chips"
 license = "MIT OR Apache-2.0"
+repository = "https://github.com/embassy-rs/embassy"
+categories = [
+    "embedded",
+    "no-std",
+    "asynchronous",
+]
 
 [package.metadata.embassy_docs]
 src_base = "https://github.com/embassy-rs/embassy/blob/embassy-boot-nrf-v$VERSION/embassy-boot/stm32/src/"

embassy-net-adin1110/Cargo.toml

@@ -6,8 +6,7 @@ keywords = ["embedded", "ADIN1110", "embassy-net", "embedded-hal-async", "ethern
 categories = ["embedded", "hardware-support", "no-std", "network-programming", "async"]
 license = "MIT OR Apache-2.0"
 edition = "2021"
-
+repository = "https://github.com/embassy-rs/embassy"
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
 heapless = "0.8"

embassy-net-adin1110/src/crc32.rs

@@ -1,3 +1,4 @@
+/// CRC32 lookup table.
 pub const CRC32R_LOOKUP_TABLE: [u32; 256] = [
     0x0000_0000,
     0x7707_3096,
@@ -263,8 +264,9 @@ pub const CRC32R_LOOKUP_TABLE: [u32; 256] = [
 pub struct ETH_FCS(pub u32);
 
 impl ETH_FCS {
-    pub const CRC32_OK: u32 = 0x2144_df1c;
+    const CRC32_OK: u32 = 0x2144_df1c;
 
+    /// Create a new frame check sequence from `data`.
     #[must_use]
     pub fn new(data: &[u8]) -> Self {
         let fcs = data.iter().fold(u32::MAX, |crc, byte| {
@@ -274,6 +276,7 @@ impl ETH_FCS {
         Self(fcs)
     }
 
+    /// Update the frame check sequence with `data`.
     #[must_use]
     pub fn update(self, data: &[u8]) -> Self {
         let fcs = data.iter().fold(self.0 ^ u32::MAX, |crc, byte| {
@@ -283,16 +286,19 @@ impl ETH_FCS {
         Self(fcs)
     }
 
+    /// Check if the frame check sequence is correct.
     #[must_use]
     pub fn crc_ok(&self) -> bool {
         self.0 == Self::CRC32_OK
     }
 
+    /// Switch byte order.
     #[must_use]
     pub fn hton_bytes(&self) -> [u8; 4] {
         self.0.to_le_bytes()
     }
 
+    /// Switch byte order as a u32.
     #[must_use]
     pub fn hton(&self) -> u32 {
         self.0.to_le()

embassy-net-adin1110/src/lib.rs

@@ -5,6 +5,7 @@
 #![allow(clippy::missing_errors_doc)]
 #![allow(clippy::missing_panics_doc)]
 #![doc = include_str!("../README.md")]
+#![warn(missing_docs)]
 
 // must go first!
 mod fmt;
@@ -26,8 +27,9 @@ use embedded_hal_async::digital::Wait;
 use embedded_hal_async::spi::{Error, Operation, SpiDevice};
 use heapless::Vec;
 pub use mdio::MdioBus;
-pub use phy::{Phy10BaseT1x, RegsC22, RegsC45};
+pub use phy::Phy10BaseT1x;
-pub use regs::{Config0, Config2, SpiRegisters as sr, Status0, Status1};
+use phy::{RegsC22, RegsC45};
+use regs::{Config0, Config2, SpiRegisters as sr, Status0, Status1};
 
 use crate::fmt::Bytes;
 use crate::regs::{LedCntrl, LedFunc, LedPol, LedPolarity, SpiHeader};
@@ -446,6 +448,7 @@ pub struct Runner<'d, SPI, INT, RST> {
 }
 
 impl<'d, SPI: SpiDevice, INT: Wait, RST: OutputPin> Runner<'d, SPI, INT, RST> {
+    /// Run the driver.
     #[allow(clippy::too_many_lines)]
     pub async fn run(mut self) -> ! {
         loop {

embassy-net-adin1110/src/mdio.rs

@@ -39,6 +39,7 @@ enum Reg13Op {
 ///
 /// Clause 45 methodes are bases on <https://www.ieee802.org/3/efm/public/nov02/oam/pannell_oam_1_1102.pdf>
 pub trait MdioBus {
+    /// Error type.
     type Error;
 
     /// Read, Clause 22

embassy-net-adin1110/src/regs.rs

@@ -2,6 +2,7 @@ use core::fmt::{Debug, Display};
 
 use bitfield::{bitfield, bitfield_bitrange, bitfield_fields};
 
+#[allow(missing_docs)]
 #[allow(non_camel_case_types)]
 #[derive(Debug, Copy, Clone)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]

embassy-net-driver-channel/src/lib.rs

@@ -1,5 +1,6 @@
 #![no_std]
 #![doc = include_str!("../README.md")]
+#![warn(missing_docs)]
 
 // must go first!
 mod fmt;
@@ -15,6 +16,9 @@ use embassy_sync::blocking_mutex::Mutex;
 use embassy_sync::waitqueue::WakerRegistration;
 use embassy_sync::zerocopy_channel;
 
+/// Channel state.
+///
+/// Holds a buffer of packets with size MTU, for both TX and RX.
 pub struct State<const MTU: usize, const N_RX: usize, const N_TX: usize> {
     rx: [PacketBuf<MTU>; N_RX],
     tx: [PacketBuf<MTU>; N_TX],
@@ -24,6 +28,7 @@ pub struct State<const MTU: usize, const N_RX: usize, const N_TX: usize> {
 impl<const MTU: usize, const N_RX: usize, const N_TX: usize> State<MTU, N_RX, N_TX> {
     const NEW_PACKET: PacketBuf<MTU> = PacketBuf::new();
 
+    /// Create a new channel state.
     pub const fn new() -> Self {
         Self {
             rx: [Self::NEW_PACKET; N_RX],
@@ -39,33 +44,45 @@ struct StateInner<'d, const MTU: usize> {
     shared: Mutex<NoopRawMutex, RefCell<Shared>>,
 }
 
-/// State of the LinkState
 struct Shared {
     link_state: LinkState,
     waker: WakerRegistration,
     hardware_address: driver::HardwareAddress,
 }
 
+/// Channel runner.
+///
+/// Holds the shared state and the lower end of channels for inbound and outbound packets.
 pub struct Runner<'d, const MTU: usize> {
     tx_chan: zerocopy_channel::Receiver<'d, NoopRawMutex, PacketBuf<MTU>>,
     rx_chan: zerocopy_channel::Sender<'d, NoopRawMutex, PacketBuf<MTU>>,
     shared: &'d Mutex<NoopRawMutex, RefCell<Shared>>,
 }
 
+/// State runner.
+///
+/// Holds the shared state of the channel such as link state.
 #[derive(Clone, Copy)]
 pub struct StateRunner<'d> {
     shared: &'d Mutex<NoopRawMutex, RefCell<Shared>>,
 }
 
+/// RX runner.
+///
+/// Holds the lower end of the channel for passing inbound packets up the stack.
 pub struct RxRunner<'d, const MTU: usize> {
     rx_chan: zerocopy_channel::Sender<'d, NoopRawMutex, PacketBuf<MTU>>,
 }
 
+/// TX runner.
+///
+/// Holds the lower end of the channel for passing outbound packets down the stack.
 pub struct TxRunner<'d, const MTU: usize> {
     tx_chan: zerocopy_channel::Receiver<'d, NoopRawMutex, PacketBuf<MTU>>,
 }
 
 impl<'d, const MTU: usize> Runner<'d, MTU> {
+    /// Split the runner into separate runners for controlling state, rx and tx.
     pub fn split(self) -> (StateRunner<'d>, RxRunner<'d, MTU>, TxRunner<'d, MTU>) {
         (
             StateRunner { shared: self.shared },
@@ -74,6 +91,7 @@ impl<'d, const MTU: usize> Runner<'d, MTU> {
         )
     }
 
+    /// Split the runner into separate runners for controlling state, rx and tx borrowing the underlying state.
     pub fn borrow_split(&mut self) -> (StateRunner<'_>, RxRunner<'_, MTU>, TxRunner<'_, MTU>) {
         (
             StateRunner { shared: self.shared },
@@ -86,10 +104,12 @@ impl<'d, const MTU: usize> Runner<'d, MTU> {
         )
     }
 
+    /// Create a state runner sharing the state channel.
     pub fn state_runner(&self) -> StateRunner<'d> {
         StateRunner { shared: self.shared }
     }
 
+    /// Set the link state.
     pub fn set_link_state(&mut self, state: LinkState) {
         self.shared.lock(|s| {
             let s = &mut *s.borrow_mut();
@@ -98,6 +118,7 @@ impl<'d, const MTU: usize> Runner<'d, MTU> {
         });
     }
 
+    /// Set the hardware address.
     pub fn set_hardware_address(&mut self, address: driver::HardwareAddress) {
         self.shared.lock(|s| {
             let s = &mut *s.borrow_mut();
@@ -106,16 +127,19 @@ impl<'d, const MTU: usize> Runner<'d, MTU> {
         });
     }
 
+    /// Wait until there is space for more inbound packets and return a slice they can be copied into.
     pub async fn rx_buf(&mut self) -> &mut [u8] {
         let p = self.rx_chan.send().await;
         &mut p.buf
     }
 
+    /// Check if there is space for more inbound packets right now.
     pub fn try_rx_buf(&mut self) -> Option<&mut [u8]> {
         let p = self.rx_chan.try_send()?;
         Some(&mut p.buf)
     }
 
+    /// Polling the inbound channel if there is space for packets.
     pub fn poll_rx_buf(&mut self, cx: &mut Context) -> Poll<&mut [u8]> {
         match self.rx_chan.poll_send(cx) {
             Poll::Ready(p) => Poll::Ready(&mut p.buf),
@@ -123,22 +147,26 @@ impl<'d, const MTU: usize> Runner<'d, MTU> {
         }
     }
 
+    /// Mark packet of len bytes as pushed to the inbound channel.
     pub fn rx_done(&mut self, len: usize) {
         let p = self.rx_chan.try_send().unwrap();
         p.len = len;
         self.rx_chan.send_done();
     }
 
+    /// Wait until there is space for more outbound packets and return a slice they can be copied into.
     pub async fn tx_buf(&mut self) -> &mut [u8] {
         let p = self.tx_chan.receive().await;
         &mut p.buf[..p.len]
     }
 
+    /// Check if there is space for more outbound packets right now.
     pub fn try_tx_buf(&mut self) -> Option<&mut [u8]> {
         let p = self.tx_chan.try_receive()?;
         Some(&mut p.buf[..p.len])
     }
 
+    /// Polling the outbound channel if there is space for packets.
     pub fn poll_tx_buf(&mut self, cx: &mut Context) -> Poll<&mut [u8]> {
         match self.tx_chan.poll_receive(cx) {
             Poll::Ready(p) => Poll::Ready(&mut p.buf[..p.len]),
@@ -146,12 +174,14 @@ impl<'d, const MTU: usize> Runner<'d, MTU> {
         }
     }
 
+    /// Mark outbound packet as copied.
     pub fn tx_done(&mut self) {
         self.tx_chan.receive_done();
     }
 }
 
 impl<'d> StateRunner<'d> {
+    /// Set link state.
     pub fn set_link_state(&self, state: LinkState) {
         self.shared.lock(|s| {
             let s = &mut *s.borrow_mut();
@@ -160,6 +190,7 @@ impl<'d> StateRunner<'d> {
         });
     }
 
+    /// Set the hardware address.
     pub fn set_hardware_address(&self, address: driver::HardwareAddress) {
         self.shared.lock(|s| {
             let s = &mut *s.borrow_mut();
@@ -170,16 +201,19 @@ impl<'d> StateRunner<'d> {
 }
 
 impl<'d, const MTU: usize> RxRunner<'d, MTU> {
+    /// Wait until there is space for more inbound packets and return a slice they can be copied into.
     pub async fn rx_buf(&mut self) -> &mut [u8] {
         let p = self.rx_chan.send().await;
         &mut p.buf
     }
 
+    /// Check if there is space for more inbound packets right now.
     pub fn try_rx_buf(&mut self) -> Option<&mut [u8]> {
         let p = self.rx_chan.try_send()?;
         Some(&mut p.buf)
     }
 
+    /// Polling the inbound channel if there is space for packets.
     pub fn poll_rx_buf(&mut self, cx: &mut Context) -> Poll<&mut [u8]> {
         match self.rx_chan.poll_send(cx) {
             Poll::Ready(p) => Poll::Ready(&mut p.buf),
@@ -187,6 +221,7 @@ impl<'d, const MTU: usize> RxRunner<'d, MTU> {
         }
     }
 
+    /// Mark packet of len bytes as pushed to the inbound channel.
     pub fn rx_done(&mut self, len: usize) {
         let p = self.rx_chan.try_send().unwrap();
         p.len = len;
@@ -195,16 +230,19 @@ impl<'d, const MTU: usize> RxRunner<'d, MTU> {
 }
 
 impl<'d, const MTU: usize> TxRunner<'d, MTU> {
+    /// Wait until there is space for more outbound packets and return a slice they can be copied into.
     pub async fn tx_buf(&mut self) -> &mut [u8] {
         let p = self.tx_chan.receive().await;
         &mut p.buf[..p.len]
     }
 
+    /// Check if there is space for more outbound packets right now.
     pub fn try_tx_buf(&mut self) -> Option<&mut [u8]> {
         let p = self.tx_chan.try_receive()?;
         Some(&mut p.buf[..p.len])
     }
 
+    /// Polling the outbound channel if there is space for packets.
     pub fn poll_tx_buf(&mut self, cx: &mut Context) -> Poll<&mut [u8]> {
         match self.tx_chan.poll_receive(cx) {
             Poll::Ready(p) => Poll::Ready(&mut p.buf[..p.len]),
@@ -212,11 +250,18 @@ impl<'d, const MTU: usize> TxRunner<'d, MTU> {
         }
     }
 
+    /// Mark outbound packet as copied.
     pub fn tx_done(&mut self) {
         self.tx_chan.receive_done();
     }
 }
 
+/// Create a channel.
+///
+/// Returns a pair of handles for interfacing with the peripheral and the networking stack.
+///
+/// The runner is interfacing with the peripheral at the lower part of the stack.
+/// The device is interfacing with the networking stack on the layer above.
 pub fn new<'d, const MTU: usize, const N_RX: usize, const N_TX: usize>(
     state: &'d mut State<MTU, N_RX, N_TX>,
     hardware_address: driver::HardwareAddress,
@@ -257,17 +302,22 @@ pub fn new<'d, const MTU: usize, const N_RX: usize, const N_TX: usize>(
     )
 }
 
+/// Represents a packet of size MTU.
 pub struct PacketBuf<const MTU: usize> {
     len: usize,
     buf: [u8; MTU],
 }
 
 impl<const MTU: usize> PacketBuf<MTU> {
+    /// Create a new packet buffer.
     pub const fn new() -> Self {
         Self { len: 0, buf: [0; MTU] }
     }
 }
 
+/// Channel device.
+///
+/// Holds the shared state and upper end of channels for inbound and outbound packets.
 pub struct Device<'d, const MTU: usize> {
     rx: zerocopy_channel::Receiver<'d, NoopRawMutex, PacketBuf<MTU>>,
     tx: zerocopy_channel::Sender<'d, NoopRawMutex, PacketBuf<MTU>>,
@@ -314,6 +364,9 @@ impl<'d, const MTU: usize> embassy_net_driver::Driver for Device<'d, MTU> {
     }
 }
 
+/// A rx token.
+///
+/// Holds inbound receive channel and interfaces with embassy-net-driver.
 pub struct RxToken<'a, const MTU: usize> {
     rx: zerocopy_channel::Receiver<'a, NoopRawMutex, PacketBuf<MTU>>,
 }
@@ -331,6 +384,9 @@ impl<'a, const MTU: usize> embassy_net_driver::RxToken for RxToken<'a, MTU> {
     }
 }
 
+/// A tx token.
+///
+/// Holds outbound transmit channel and interfaces with embassy-net-driver.
 pub struct TxToken<'a, const MTU: usize> {
     tx: zerocopy_channel::Sender<'a, NoopRawMutex, PacketBuf<MTU>>,
 }

embassy-net-esp-hosted/Cargo.toml

@@ -2,6 +2,10 @@
 name = "embassy-net-esp-hosted"
 version = "0.1.0"
 edition = "2021"
+description = "embassy-net driver for ESP-Hosted"
+keywords = ["embedded", "esp-hosted", "embassy-net", "embedded-hal-async", "wifi", "async"]
+categories = ["embedded", "hardware-support", "no-std", "network-programming", "async"]
+license = "MIT OR Apache-2.0"
 
 [dependencies]
 defmt = { version = "0.3", optional = true }
@@ -15,8 +19,7 @@ embassy-net-driver-channel = { version = "0.2.0", path = "../embassy-net-driver-
 embedded-hal = { version = "1.0.0-rc.3" }
 embedded-hal-async = { version = "=1.0.0-rc.3" }
 
-noproto = { git="https://github.com/embassy-rs/noproto", rev = "f5e6d1f325b6ad4e344f60452b09576e24671f62", default-features = false, features = ["derive"] }
+noproto = "0.1.0"
-#noproto = { version = "0.1", path = "/home/dirbaio/noproto", default-features = false, features = ["derive"] }
 heapless = "0.8"
 
 [package.metadata.embassy_docs]

embassy-net-esp-hosted/README.md

@@ -0,0 +1,27 @@
+# ESP-Hosted `embassy-net` integration
+
+[`embassy-net`](https://crates.io/crates/embassy-net) integration for Espressif SoCs running the the ESP-Hosted stack.
+
+See [`examples`](https://github.com/embassy-rs/embassy/tree/main/examples/nrf52840) directory for usage examples with the nRF52840.
+
+## Supported chips
+
+- W5500
+- W5100S
+
+## Interoperability
+
+This crate can run on any executor.
+
+It supports any SPI driver implementing [`embedded-hal-async`](https://crates.io/crates/embedded-hal-async).
+
+
+## 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-net-esp-hosted/src/control.rs

@@ -5,38 +5,54 @@ use heapless::String;
 use crate::ioctl::Shared;
 use crate::proto::{self, CtrlMsg};
 
+/// Errors reported by control.
 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Error {
+    /// The operation failed with the given error code.
     Failed(u32),
+    /// The operation timed out.
     Timeout,
+    /// Internal error.
     Internal,
 }
 
+/// Handle for managing the network and WiFI state.
 pub struct Control<'a> {
     state_ch: ch::StateRunner<'a>,
     shared: &'a Shared,
 }
 
+/// WiFi mode.
 #[allow(unused)]
 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 enum WifiMode {
+    /// No mode.
     None = 0,
+    /// Client station.
     Sta = 1,
+    /// Access point mode.
     Ap = 2,
+    /// Repeater mode.
     ApSta = 3,
 }
 
 pub use proto::CtrlWifiSecProt as Security;
 
+/// WiFi status.
 #[derive(Clone, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct Status {
+    /// Service Set Identifier.
     pub ssid: String<32>,
+    /// Basic Service Set Identifier.
     pub bssid: [u8; 6],
+    /// Received Signal Strength Indicator.
     pub rssi: i32,
+    /// WiFi channel.
     pub channel: u32,
+    /// Security mode.
     pub security: Security,
 }
 
@@ -65,6 +81,7 @@ impl<'a> Control<'a> {
         Self { state_ch, shared }
     }
 
+    /// Initialize device.
     pub async fn init(&mut self) -> Result<(), Error> {
         debug!("wait for init event...");
         self.shared.init_wait().await;
@@ -82,6 +99,7 @@ impl<'a> Control<'a> {
         Ok(())
     }
 
+    /// Get the current status.
     pub async fn get_status(&mut self) -> Result<Status, Error> {
         let req = proto::CtrlMsgReqGetApConfig {};
         ioctl!(self, ReqGetApConfig, RespGetApConfig, req, resp);
@@ -95,6 +113,7 @@ impl<'a> Control<'a> {
         })
     }
 
+    /// Connect to the network identified by ssid using the provided password.
     pub async fn connect(&mut self, ssid: &str, password: &str) -> Result<(), Error> {
         let req = proto::CtrlMsgReqConnectAp {
             ssid: unwrap!(String::try_from(ssid)),
@@ -108,6 +127,7 @@ impl<'a> Control<'a> {
         Ok(())
     }
 
+    /// Disconnect from any currently connected network.
     pub async fn disconnect(&mut self) -> Result<(), Error> {
         let req = proto::CtrlMsgReqGetStatus {};
         ioctl!(self, ReqDisconnectAp, RespDisconnectAp, req, resp);

embassy-net-esp-hosted/src/lib.rs

@@ -1,4 +1,6 @@
 #![no_std]
+#![doc = include_str!("../README.md")]
+#![warn(missing_docs)]
 
 use embassy_futures::select::{select4, Either4};
 use embassy_net_driver_channel as ch;
@@ -97,12 +99,14 @@ enum InterfaceType {
 const MAX_SPI_BUFFER_SIZE: usize = 1600;
 const HEARTBEAT_MAX_GAP: Duration = Duration::from_secs(20);
 
+/// State for the esp-hosted driver.
 pub struct State {
     shared: Shared,
     ch: ch::State<MTU, 4, 4>,
 }
 
 impl State {
+    /// Create a new state.
     pub fn new() -> Self {
         Self {
             shared: Shared::new(),
@@ -111,8 +115,13 @@ impl State {
     }
 }
 
+/// Type alias for network driver.
 pub type NetDriver<'a> = ch::Device<'a, MTU>;
 
+/// Create a new esp-hosted driver using the provided state, SPI peripheral and pins.
+///
+/// Returns a device handle for interfacing with embassy-net, a control handle for
+/// interacting with the driver, and a runner for communicating with the WiFi device.
 pub async fn new<'a, SPI, IN, OUT>(
     state: &'a mut State,
     spi: SPI,
@@ -144,6 +153,7 @@ where
     (device, Control::new(state_ch, &state.shared), runner)
 }
 
+/// Runner for communicating with the WiFi device.
 pub struct Runner<'a, SPI, IN, OUT> {
     ch: ch::Runner<'a, MTU>,
     state_ch: ch::StateRunner<'a>,
@@ -166,6 +176,7 @@ where
 {
     async fn init(&mut self) {}
 
+    /// Run the packet processing.
     pub async fn run(mut self) -> ! {
         debug!("resetting...");
         self.reset.set_low().unwrap();

embassy-net-esp-hosted/src/proto.rs

@@ -4,7 +4,7 @@ use heapless::{String, Vec};
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct ScanResult {
+pub(crate) struct ScanResult {
     #[noproto(tag = "1")]
     pub ssid: String<32>,
     #[noproto(tag = "2")]
@@ -19,7 +19,7 @@ pub struct ScanResult {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct ConnectedStaList {
+pub(crate) struct ConnectedStaList {
     #[noproto(tag = "1")]
     pub mac: String<32>,
     #[noproto(tag = "2")]
@@ -29,14 +29,14 @@ pub struct ConnectedStaList {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqGetMacAddress {
+pub(crate) struct CtrlMsgReqGetMacAddress {
     #[noproto(tag = "1")]
     pub mode: u32,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespGetMacAddress {
+pub(crate) struct CtrlMsgRespGetMacAddress {
     #[noproto(tag = "1")]
     pub mac: String<32>,
     #[noproto(tag = "2")]
@@ -45,11 +45,11 @@ pub struct CtrlMsgRespGetMacAddress {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqGetMode {}
+pub(crate) struct CtrlMsgReqGetMode {}
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespGetMode {
+pub(crate) struct CtrlMsgRespGetMode {
     #[noproto(tag = "1")]
     pub mode: u32,
     #[noproto(tag = "2")]
@@ -58,32 +58,32 @@ pub struct CtrlMsgRespGetMode {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqSetMode {
+pub(crate) struct CtrlMsgReqSetMode {
     #[noproto(tag = "1")]
     pub mode: u32,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespSetMode {
+pub(crate) struct CtrlMsgRespSetMode {
     #[noproto(tag = "1")]
     pub resp: u32,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqGetStatus {}
+pub(crate) struct CtrlMsgReqGetStatus {}
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespGetStatus {
+pub(crate) struct CtrlMsgRespGetStatus {
     #[noproto(tag = "1")]
     pub resp: u32,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqSetMacAddress {
+pub(crate) struct CtrlMsgReqSetMacAddress {
     #[noproto(tag = "1")]
     pub mac: String<32>,
     #[noproto(tag = "2")]
@@ -92,18 +92,18 @@ pub struct CtrlMsgReqSetMacAddress {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespSetMacAddress {
+pub(crate) struct CtrlMsgRespSetMacAddress {
     #[noproto(tag = "1")]
     pub resp: u32,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqGetApConfig {}
+pub(crate) struct CtrlMsgReqGetApConfig {}
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespGetApConfig {
+pub(crate) struct CtrlMsgRespGetApConfig {
     #[noproto(tag = "1")]
     pub ssid: String<32>,
     #[noproto(tag = "2")]
@@ -120,7 +120,7 @@ pub struct CtrlMsgRespGetApConfig {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqConnectAp {
+pub(crate) struct CtrlMsgReqConnectAp {
     #[noproto(tag = "1")]
     pub ssid: String<32>,
     #[noproto(tag = "2")]
@@ -135,7 +135,7 @@ pub struct CtrlMsgReqConnectAp {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespConnectAp {
+pub(crate) struct CtrlMsgRespConnectAp {
     #[noproto(tag = "1")]
     pub resp: u32,
     #[noproto(tag = "2")]
@@ -144,11 +144,11 @@ pub struct CtrlMsgRespConnectAp {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqGetSoftApConfig {}
+pub(crate) struct CtrlMsgReqGetSoftApConfig {}
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespGetSoftApConfig {
+pub(crate) struct CtrlMsgRespGetSoftApConfig {
     #[noproto(tag = "1")]
     pub ssid: String<32>,
     #[noproto(tag = "2")]
@@ -169,7 +169,7 @@ pub struct CtrlMsgRespGetSoftApConfig {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqStartSoftAp {
+pub(crate) struct CtrlMsgReqStartSoftAp {
     #[noproto(tag = "1")]
     pub ssid: String<32>,
     #[noproto(tag = "2")]
@@ -188,7 +188,7 @@ pub struct CtrlMsgReqStartSoftAp {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespStartSoftAp {
+pub(crate) struct CtrlMsgRespStartSoftAp {
     #[noproto(tag = "1")]
     pub resp: u32,
     #[noproto(tag = "2")]
@@ -197,11 +197,11 @@ pub struct CtrlMsgRespStartSoftAp {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqScanResult {}
+pub(crate) struct CtrlMsgReqScanResult {}
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespScanResult {
+pub(crate) struct CtrlMsgRespScanResult {
     #[noproto(tag = "1")]
     pub count: u32,
     #[noproto(repeated, tag = "2")]
@@ -212,11 +212,11 @@ pub struct CtrlMsgRespScanResult {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqSoftApConnectedSta {}
+pub(crate) struct CtrlMsgReqSoftApConnectedSta {}
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespSoftApConnectedSta {
+pub(crate) struct CtrlMsgRespSoftApConnectedSta {
     #[noproto(tag = "1")]
     pub num: u32,
     #[noproto(repeated, tag = "2")]
@@ -227,43 +227,43 @@ pub struct CtrlMsgRespSoftApConnectedSta {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqOtaBegin {}
+pub(crate) struct CtrlMsgReqOtaBegin {}
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespOtaBegin {
+pub(crate) struct CtrlMsgRespOtaBegin {
     #[noproto(tag = "1")]
     pub resp: u32,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqOtaWrite {
+pub(crate) struct CtrlMsgReqOtaWrite {
     #[noproto(tag = "1")]
     pub ota_data: Vec<u8, 1024>,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespOtaWrite {
+pub(crate) struct CtrlMsgRespOtaWrite {
     #[noproto(tag = "1")]
     pub resp: u32,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqOtaEnd {}
+pub(crate) struct CtrlMsgReqOtaEnd {}
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespOtaEnd {
+pub(crate) struct CtrlMsgRespOtaEnd {
     #[noproto(tag = "1")]
     pub resp: u32,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqVendorIeData {
+pub(crate) struct CtrlMsgReqVendorIeData {
     #[noproto(tag = "1")]
     pub element_id: u32,
     #[noproto(tag = "2")]
@@ -278,7 +278,7 @@ pub struct CtrlMsgReqVendorIeData {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqSetSoftApVendorSpecificIe {
+pub(crate) struct CtrlMsgReqSetSoftApVendorSpecificIe {
     #[noproto(tag = "1")]
     pub enable: bool,
     #[noproto(tag = "2")]
@@ -291,32 +291,32 @@ pub struct CtrlMsgReqSetSoftApVendorSpecificIe {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespSetSoftApVendorSpecificIe {
+pub(crate) struct CtrlMsgRespSetSoftApVendorSpecificIe {
     #[noproto(tag = "1")]
     pub resp: u32,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqSetWifiMaxTxPower {
+pub(crate) struct CtrlMsgReqSetWifiMaxTxPower {
     #[noproto(tag = "1")]
     pub wifi_max_tx_power: u32,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespSetWifiMaxTxPower {
+pub(crate) struct CtrlMsgRespSetWifiMaxTxPower {
     #[noproto(tag = "1")]
     pub resp: u32,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqGetWifiCurrTxPower {}
+pub(crate) struct CtrlMsgReqGetWifiCurrTxPower {}
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespGetWifiCurrTxPower {
+pub(crate) struct CtrlMsgRespGetWifiCurrTxPower {
     #[noproto(tag = "1")]
     pub wifi_curr_tx_power: u32,
     #[noproto(tag = "2")]
@@ -325,7 +325,7 @@ pub struct CtrlMsgRespGetWifiCurrTxPower {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgReqConfigHeartbeat {
+pub(crate) struct CtrlMsgReqConfigHeartbeat {
     #[noproto(tag = "1")]
     pub enable: bool,
     #[noproto(tag = "2")]
@@ -334,7 +334,7 @@ pub struct CtrlMsgReqConfigHeartbeat {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgRespConfigHeartbeat {
+pub(crate) struct CtrlMsgRespConfigHeartbeat {
     #[noproto(tag = "1")]
     pub resp: u32,
 }
@@ -342,28 +342,28 @@ pub struct CtrlMsgRespConfigHeartbeat {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgEventEspInit {
+pub(crate) struct CtrlMsgEventEspInit {
     #[noproto(tag = "1")]
     pub init_data: Vec<u8, 64>,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgEventHeartbeat {
+pub(crate) struct CtrlMsgEventHeartbeat {
     #[noproto(tag = "1")]
     pub hb_num: u32,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgEventStationDisconnectFromAp {
+pub(crate) struct CtrlMsgEventStationDisconnectFromAp {
     #[noproto(tag = "1")]
     pub resp: u32,
 }
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsgEventStationDisconnectFromEspSoftAp {
+pub(crate) struct CtrlMsgEventStationDisconnectFromEspSoftAp {
     #[noproto(tag = "1")]
     pub resp: u32,
     #[noproto(tag = "2")]
@@ -372,7 +372,7 @@ pub struct CtrlMsgEventStationDisconnectFromEspSoftAp {
 
 #[derive(Debug, Default, Clone, Eq, PartialEq, noproto::Message)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub struct CtrlMsg {
+pub(crate) struct CtrlMsg {
     /// msg_type could be req, resp or Event
     #[noproto(tag = "1")]
     pub msg_type: CtrlMsgType,
@@ -390,7 +390,7 @@ pub struct CtrlMsg {
 /// union of all msg ids
 #[derive(Debug, Clone, Eq, PartialEq, noproto::Oneof)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub enum CtrlMsgPayload {
+pub(crate) enum CtrlMsgPayload {
     /// * Requests *
     #[noproto(tag = "101")]
     ReqGetMacAddress(CtrlMsgReqGetMacAddress),
@@ -492,7 +492,7 @@ pub enum CtrlMsgPayload {
 #[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Hash, PartialOrd, Ord, noproto::Enumeration)]
 #[repr(u32)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub enum CtrlVendorIeType {
+pub(crate) enum CtrlVendorIeType {
     #[default]
     Beacon = 0,
     ProbeReq = 1,
@@ -504,7 +504,7 @@ pub enum CtrlVendorIeType {
 #[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Hash, PartialOrd, Ord, noproto::Enumeration)]
 #[repr(u32)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub enum CtrlVendorIeid {
+pub(crate) enum CtrlVendorIeid {
     #[default]
     Id0 = 0,
     Id1 = 1,
@@ -513,7 +513,7 @@ pub enum CtrlVendorIeid {
 #[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Hash, PartialOrd, Ord, noproto::Enumeration)]
 #[repr(u32)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub enum CtrlWifiMode {
+pub(crate) enum CtrlWifiMode {
     #[default]
     None = 0,
     Sta = 1,
@@ -524,7 +524,7 @@ pub enum CtrlWifiMode {
 #[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Hash, PartialOrd, Ord, noproto::Enumeration)]
 #[repr(u32)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub enum CtrlWifiBw {
+pub(crate) enum CtrlWifiBw {
     #[default]
     BwInvalid = 0,
     Ht20 = 1,
@@ -534,13 +534,15 @@ pub enum CtrlWifiBw {
 #[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Hash, PartialOrd, Ord, noproto::Enumeration)]
 #[repr(u32)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub enum CtrlWifiPowerSave {
+pub(crate) enum CtrlWifiPowerSave {
     #[default]
     PsInvalid = 0,
     MinModem = 1,
     MaxModem = 2,
 }
 
+/// Wifi Security Settings
+#[allow(missing_docs)]
 #[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Hash, PartialOrd, Ord, noproto::Enumeration)]
 #[repr(u32)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
@@ -560,7 +562,7 @@ pub enum CtrlWifiSecProt {
 #[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Hash, PartialOrd, Ord, noproto::Enumeration)]
 #[repr(u32)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub enum CtrlStatus {
+pub(crate) enum CtrlStatus {
     #[default]
     Connected = 0,
     NotConnected = 1,
@@ -573,7 +575,7 @@ pub enum CtrlStatus {
 #[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Hash, PartialOrd, Ord, noproto::Enumeration)]
 #[repr(u32)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub enum CtrlMsgType {
+pub(crate) enum CtrlMsgType {
     #[default]
     MsgTypeInvalid = 0,
     Req = 1,
@@ -585,7 +587,7 @@ pub enum CtrlMsgType {
 #[derive(Debug, Default, Clone, Copy, Eq, PartialEq, Hash, PartialOrd, Ord, noproto::Enumeration)]
 #[repr(u32)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub enum CtrlMsgId {
+pub(crate) enum CtrlMsgId {
     #[default]
     MsgIdInvalid = 0,
     /// * Request Msgs *

embassy-net-tuntap/Cargo.toml

@@ -6,6 +6,7 @@ keywords = ["embedded", "tuntap", "embassy-net", "embedded-hal-async", "ethernet
 categories = ["embedded", "hardware-support", "no-std", "network-programming", "async"]
 license = "MIT OR Apache-2.0"
 edition = "2021"
+repository = "https://github.com/embassy-rs/embassy"
 
 [dependencies]
 embassy-net-driver = { version = "0.2.0", path = "../embassy-net-driver" }
@@ -16,4 +17,4 @@ libc = "0.2.101"
 [package.metadata.embassy_docs]
 src_base = "https://github.com/embassy-rs/embassy/blob/embassy-net-tuntap-v$VERSION/embassy-net-tuntap/src/"
 src_base_git = "https://github.com/embassy-rs/embassy/blob/$COMMIT/embassy-net-tuntap/src/"
-target = "thumbv7em-none-eabi"
+target = "thumbv7em-none-eabi"

embassy-net-tuntap/src/lib.rs

@@ -1,3 +1,5 @@
+#![warn(missing_docs)]
+#![doc = include_str!("../README.md")]
 use std::io;
 use std::io::{Read, Write};
 use std::os::unix::io::{AsRawFd, RawFd};
@@ -7,12 +9,19 @@ use async_io::Async;
 use embassy_net_driver::{self, Capabilities, Driver, HardwareAddress, LinkState};
 use log::*;
 
+/// Get the MTU of the given interface.
 pub const SIOCGIFMTU: libc::c_ulong = 0x8921;
+/// Get the index of the given interface.
 pub const _SIOCGIFINDEX: libc::c_ulong = 0x8933;
+/// Capture all packages.
 pub const _ETH_P_ALL: libc::c_short = 0x0003;
+/// Set the interface flags.
 pub const TUNSETIFF: libc::c_ulong = 0x400454CA;
+/// TUN device.
 pub const _IFF_TUN: libc::c_int = 0x0001;
+/// TAP device.
 pub const IFF_TAP: libc::c_int = 0x0002;
+/// No packet information.
 pub const IFF_NO_PI: libc::c_int = 0x1000;
 
 const ETHERNET_HEADER_LEN: usize = 14;
@@ -47,6 +56,7 @@ fn ifreq_ioctl(lower: libc::c_int, ifreq: &mut ifreq, cmd: libc::c_ulong) -> io:
     Ok(ifreq.ifr_data)
 }
 
+/// A TUN/TAP device.
 #[derive(Debug)]
 pub struct TunTap {
     fd: libc::c_int,
@@ -60,6 +70,7 @@ impl AsRawFd for TunTap {
 }
 
 impl TunTap {
+    /// Create a new TUN/TAP device.
     pub fn new(name: &str) -> io::Result<TunTap> {
         unsafe {
             let fd = libc::open(
@@ -126,11 +137,13 @@ impl io::Write for TunTap {
     }
 }
 
+/// A TUN/TAP device, wrapped in an async interface.
 pub struct TunTapDevice {
     device: Async<TunTap>,
 }
 
 impl TunTapDevice {
+    /// Create a new TUN/TAP device.
     pub fn new(name: &str) -> io::Result<TunTapDevice> {
         Ok(Self {
             device: Async::new(TunTap::new(name)?)?,

embassy-net-wiznet/Cargo.toml

@@ -6,6 +6,7 @@ keywords = ["embedded", "wiznet", "embassy-net", "embedded-hal-async", "ethernet
 categories = ["embedded", "hardware-support", "no-std", "network-programming", "async"]
 license = "MIT OR Apache-2.0"
 edition = "2021"
+repository = "https://github.com/embassy-rs/embassy"
 
 [dependencies]
 embedded-hal = { version = "1.0.0-rc.3" }

embassy-net-wiznet/src/chip/mod.rs

@@ -1,3 +1,4 @@
+//! Wiznet W5100s and W5500 family driver.
 mod w5500;
 pub use w5500::W5500;
 mod w5100s;
@@ -45,4 +46,5 @@ pub(crate) mod sealed {
     }
 }
 
+/// Trait for Wiznet chips.
 pub trait Chip: sealed::Chip {}

embassy-net-wiznet/src/chip/w5100s.rs

@@ -4,6 +4,7 @@ const SOCKET_BASE: u16 = 0x400;
 const TX_BASE: u16 = 0x4000;
 const RX_BASE: u16 = 0x6000;
 
+/// Wizard W5100S chip.
 pub enum W5100S {}
 
 impl super::Chip for W5100S {}

embassy-net-wiznet/src/chip/w5500.rs

@@ -8,6 +8,7 @@ pub enum RegisterBlock {
     RxBuf = 0x03,
 }
 
+/// Wiznet W5500 chip.
 pub enum W5500 {}
 
 impl super::Chip for W5500 {}

embassy-net-wiznet/src/lib.rs

@@ -1,6 +1,7 @@
 #![no_std]
 #![allow(async_fn_in_trait)]
 #![doc = include_str!("../README.md")]
+#![warn(missing_docs)]
 
 pub mod chip;
 mod device;
@@ -47,6 +48,7 @@ pub struct Runner<'d, C: Chip, SPI: SpiDevice, INT: Wait, RST: OutputPin> {
 
 /// You must call this in a background task for the driver to operate.
 impl<'d, C: Chip, SPI: SpiDevice, INT: Wait, RST: OutputPin> Runner<'d, C, SPI, INT, RST> {
+    /// Run the driver.
     pub async fn run(mut self) -> ! {
         let (state_chan, mut rx_chan, mut tx_chan) = self.ch.split();
         let mut tick = Ticker::every(Duration::from_millis(500));

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/adc.rs

@@ -1,3 +1,4 @@
+//! ADC driver.
 use core::future::poll_fn;
 use core::marker::PhantomData;
 use core::mem;
@@ -16,6 +17,7 @@ use crate::{dma, interrupt, pac, peripherals, Peripheral, RegExt};
 
 static WAKER: AtomicWaker = AtomicWaker::new();
 
+/// ADC config.
 #[non_exhaustive]
 pub struct Config {}
 
@@ -30,9 +32,11 @@ enum Source<'p> {
     TempSensor(PeripheralRef<'p, ADC_TEMP_SENSOR>),
 }
 
+/// ADC channel.
 pub struct Channel<'p>(Source<'p>);
 
 impl<'p> Channel<'p> {
+    /// Create a new ADC channel from pin with the provided [Pull] configuration.
     pub fn new_pin(pin: impl Peripheral<P = impl AdcPin + 'p> + 'p, pull: Pull) -> Self {
         into_ref!(pin);
         pin.pad_ctrl().modify(|w| {
@@ -49,6 +53,7 @@ impl<'p> Channel<'p> {
         Self(Source::Pin(pin.map_into()))
     }
 
+    /// Create a new ADC channel for the internal temperature sensor.
     pub fn new_temp_sensor(s: impl Peripheral<P = ADC_TEMP_SENSOR> + 'p) -> Self {
         let r = pac::ADC;
         r.cs().write_set(|w| w.set_ts_en(true));
@@ -83,35 +88,44 @@ impl<'p> Drop for Source<'p> {
     }
 }
 
+/// ADC sample.
 #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug, Default)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[repr(transparent)]
 pub struct Sample(u16);
 
 impl Sample {
+    /// Sample is valid.
     pub fn good(&self) -> bool {
         self.0 < 0x8000
     }
 
+    /// Sample value.
     pub fn value(&self) -> u16 {
         self.0 & !0x8000
     }
 }
 
+/// ADC error.
 #[derive(Debug, Eq, PartialEq, Copy, Clone)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Error {
+    /// Error converting value.
     ConversionFailed,
 }
 
+/// ADC mode.
 pub trait Mode {}
 
+/// ADC async mode.
 pub struct Async;
 impl Mode for Async {}
 
+/// ADC blocking mode.
 pub struct Blocking;
 impl Mode for Blocking {}
 
+/// ADC driver.
 pub struct Adc<'d, M: Mode> {
     phantom: PhantomData<(&'d ADC, M)>,
 }
@@ -150,6 +164,7 @@ impl<'d, M: Mode> Adc<'d, M> {
         while !r.cs().read().ready() {}
     }
 
+    /// Sample a value from a channel in blocking mode.
     pub fn blocking_read(&mut self, ch: &mut Channel) -> Result<u16, Error> {
         let r = Self::regs();
         r.cs().modify(|w| {
@@ -166,6 +181,7 @@ impl<'d, M: Mode> Adc<'d, M> {
 }
 
 impl<'d> Adc<'d, Async> {
+    /// Create ADC driver in async mode.
     pub fn new(
         _inner: impl Peripheral<P = ADC> + 'd,
         _irq: impl Binding<interrupt::typelevel::ADC_IRQ_FIFO, InterruptHandler>,
@@ -194,6 +210,7 @@ impl<'d> Adc<'d, Async> {
         .await;
     }
 
+    /// Sample a value from a channel until completed.
     pub async fn read(&mut self, ch: &mut Channel<'_>) -> Result<u16, Error> {
         let r = Self::regs();
         r.cs().modify(|w| {
@@ -272,6 +289,7 @@ impl<'d> Adc<'d, Async> {
         }
     }
 
+    /// Sample multiple values from a channel using DMA.
     #[inline]
     pub async fn read_many<S: AdcSample>(
         &mut self,
@@ -283,6 +301,7 @@ impl<'d> Adc<'d, Async> {
         self.read_many_inner(ch, buf, false, div, dma).await
     }
 
+    /// Sample multiple values from a channel using DMA with errors inlined in samples.
     #[inline]
     pub async fn read_many_raw(
         &mut self,
@@ -299,6 +318,7 @@ impl<'d> Adc<'d, Async> {
 }
 
 impl<'d> Adc<'d, Blocking> {
+    /// Create ADC driver in blocking mode.
     pub fn new_blocking(_inner: impl Peripheral<P = ADC> + 'd, _config: Config) -> Self {
         Self::setup();
 
@@ -306,6 +326,7 @@ impl<'d> Adc<'d, Blocking> {
     }
 }
 
+/// Interrupt handler.
 pub struct InterruptHandler {
     _empty: (),
 }
@@ -324,6 +345,7 @@ mod sealed {
     pub trait AdcChannel {}
 }
 
+/// ADC sample.
 pub trait AdcSample: sealed::AdcSample {}
 
 impl sealed::AdcSample for u16 {}
@@ -332,7 +354,9 @@ impl AdcSample for u16 {}
 impl sealed::AdcSample for u8 {}
 impl AdcSample for u8 {}
 
+/// ADC channel.
 pub trait AdcChannel: sealed::AdcChannel {}
+/// ADC pin.
 pub trait AdcPin: AdcChannel + gpio::Pin {}
 
 macro_rules! impl_pin {

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,34 +45,50 @@ static CLOCKS: Clocks = Clocks {
     rtc: AtomicU16::new(0),
 };
 
+/// Peripheral clock sources.
 #[repr(u8)]
 #[non_exhaustive]
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum PeriClkSrc {
+    /// SYS.
     Sys = ClkPeriCtrlAuxsrc::CLK_SYS as _,
+    /// PLL SYS.
     PllSys = ClkPeriCtrlAuxsrc::CLKSRC_PLL_SYS as _,
+    /// PLL USB.
     PllUsb = ClkPeriCtrlAuxsrc::CLKSRC_PLL_USB as _,
+    /// ROSC.
     Rosc = ClkPeriCtrlAuxsrc::ROSC_CLKSRC_PH as _,
+    /// XOSC.
     Xosc = ClkPeriCtrlAuxsrc::XOSC_CLKSRC as _,
     // Gpin0 = ClkPeriCtrlAuxsrc::CLKSRC_GPIN0 as _ ,
     // 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>)>,
 }
 
 impl ClockConfig {
+    /// Clock configuration derived from external crystal.
     pub fn crystal(crystal_hz: u32) -> Self {
         Self {
             rosc: Some(RoscConfig {
@@ -130,6 +147,7 @@ impl ClockConfig {
         }
     }
 
+    /// Clock configuration from internal oscillator.
     pub fn rosc() -> Self {
         Self {
             rosc: Some(RoscConfig {
@@ -179,130 +197,190 @@ impl ClockConfig {
     // }
 }
 
+/// ROSC freq range.
 #[repr(u16)]
 #[non_exhaustive]
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum RoscRange {
+    /// Low range.
     Low = pac::rosc::vals::FreqRange::LOW.0,
+    /// Medium range (1.33x low)
     Medium = pac::rosc::vals::FreqRange::MEDIUM.0,
+    /// High range (2x low)
     High = pac::rosc::vals::FreqRange::HIGH.0,
+    /// Too high. Should not be used.
     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 clock config.
 pub struct RefClkConfig {
+    /// Reference clock source.
     pub src: RefClkSrc,
+    /// Reference clock divider.
     pub div: u8,
 }
 
+/// Reference clock source.
 #[non_exhaustive]
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum RefClkSrc {
-    // main sources
+    /// XOSC.
     Xosc,
+    /// ROSC.
     Rosc,
-    // aux sources
+    /// PLL USB.
     PllUsb,
     // Gpin0,
     // Gpin1,
 }
 
+/// SYS clock source.
 #[non_exhaustive]
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum SysClkSrc {
-    // main sources
+    /// REF.
     Ref,
-    // aux sources
+    /// PLL SYS.
     PllSys,
+    /// PLL USB.
     PllUsb,
+    /// ROSC.
     Rosc,
+    /// XOSC.
     Xosc,
     // Gpin0,
     // Gpin1,
 }
 
+/// SYS clock config.
 pub struct SysClkConfig {
+    /// SYS clock source.
     pub src: SysClkSrc,
+    /// SYS clock divider.
     pub div_int: u32,
+    /// SYS clock fraction.
     pub div_frac: u8,
 }
 
+/// USB clock source.
 #[repr(u8)]
 #[non_exhaustive]
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum UsbClkSrc {
+    /// PLL USB.
     PllUsb = ClkUsbCtrlAuxsrc::CLKSRC_PLL_USB as _,
+    /// PLL SYS.
     PllSys = ClkUsbCtrlAuxsrc::CLKSRC_PLL_SYS as _,
+    /// ROSC.
     Rosc = ClkUsbCtrlAuxsrc::ROSC_CLKSRC_PH as _,
+    /// XOSC.
     Xosc = ClkUsbCtrlAuxsrc::XOSC_CLKSRC as _,
     // Gpin0 = ClkUsbCtrlAuxsrc::CLKSRC_GPIN0 as _ ,
     // Gpin1 = ClkUsbCtrlAuxsrc::CLKSRC_GPIN1 as _ ,
 }
 
+/// USB clock config.
 pub struct UsbClkConfig {
+    /// USB clock source.
     pub src: UsbClkSrc,
+    /// USB clock divider.
     pub div: u8,
+    /// USB clock phase.
     pub phase: u8,
 }
 
+/// ADC clock source.
 #[repr(u8)]
 #[non_exhaustive]
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum AdcClkSrc {
+    /// PLL USB.
     PllUsb = ClkAdcCtrlAuxsrc::CLKSRC_PLL_USB as _,
+    /// PLL SYS.
     PllSys = ClkAdcCtrlAuxsrc::CLKSRC_PLL_SYS as _,
+    /// ROSC.
     Rosc = ClkAdcCtrlAuxsrc::ROSC_CLKSRC_PH as _,
+    /// XOSC.
     Xosc = ClkAdcCtrlAuxsrc::XOSC_CLKSRC as _,
     // Gpin0 = ClkAdcCtrlAuxsrc::CLKSRC_GPIN0 as _ ,
     // Gpin1 = ClkAdcCtrlAuxsrc::CLKSRC_GPIN1 as _ ,
 }
 
+/// ADC clock config.
 pub struct AdcClkConfig {
+    /// ADC clock source.
     pub src: AdcClkSrc,
+    /// ADC clock divider.
     pub div: u8,
+    /// ADC clock phase.
     pub phase: u8,
 }
 
+/// RTC clock source.
 #[repr(u8)]
 #[non_exhaustive]
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub enum RtcClkSrc {
+    /// PLL USB.
     PllUsb = ClkRtcCtrlAuxsrc::CLKSRC_PLL_USB as _,
+    /// PLL SYS.
     PllSys = ClkRtcCtrlAuxsrc::CLKSRC_PLL_SYS as _,
+    /// ROSC.
     Rosc = ClkRtcCtrlAuxsrc::ROSC_CLKSRC_PH as _,
+    /// XOSC.
     Xosc = ClkRtcCtrlAuxsrc::XOSC_CLKSRC as _,
     // Gpin0 = ClkRtcCtrlAuxsrc::CLKSRC_GPIN0 as _ ,
     // Gpin1 = ClkRtcCtrlAuxsrc::CLKSRC_GPIN1 as _ ,
 }
 
+/// RTC clock config.
 pub struct RtcClkConfig {
+    /// RTC clock source.
     pub src: RtcClkSrc,
+    /// RTC clock divider.
     pub div_int: u32,
+    /// RTC clock divider fraction.
     pub div_frac: u8,
+    /// RTC clock phase.
     pub phase: u8,
 }
 
@@ -579,10 +657,12 @@ fn configure_rosc(config: RoscConfig) -> u32 {
     config.hz
 }
 
+/// ROSC clock frequency.
 pub fn rosc_freq() -> u32 {
     CLOCKS.rosc.load(Ordering::Relaxed)
 }
 
+/// XOSC clock frequency.
 pub fn xosc_freq() -> u32 {
     CLOCKS.xosc.load(Ordering::Relaxed)
 }
@@ -594,34 +674,42 @@ pub fn xosc_freq() -> u32 {
 //     CLOCKS.gpin1.load(Ordering::Relaxed)
 // }
 
+/// PLL SYS clock frequency.
 pub fn pll_sys_freq() -> u32 {
     CLOCKS.pll_sys.load(Ordering::Relaxed)
 }
 
+/// PLL USB clock frequency.
 pub fn pll_usb_freq() -> u32 {
     CLOCKS.pll_usb.load(Ordering::Relaxed)
 }
 
+/// SYS clock frequency.
 pub fn clk_sys_freq() -> u32 {
     CLOCKS.sys.load(Ordering::Relaxed)
 }
 
+/// REF clock frequency.
 pub fn clk_ref_freq() -> u32 {
     CLOCKS.reference.load(Ordering::Relaxed)
 }
 
+/// Peripheral clock frequency.
 pub fn clk_peri_freq() -> u32 {
     CLOCKS.peri.load(Ordering::Relaxed)
 }
 
+/// USB clock frequency.
 pub fn clk_usb_freq() -> u32 {
     CLOCKS.usb.load(Ordering::Relaxed)
 }
 
+/// ADC clock frequency.
 pub fn clk_adc_freq() -> u32 {
     CLOCKS.adc.load(Ordering::Relaxed)
 }
 
+/// RTC clock frequency.
 pub fn clk_rtc_freq() -> u16 {
     CLOCKS.rtc.load(Ordering::Relaxed)
 }
@@ -682,7 +770,9 @@ fn configure_pll(p: pac::pll::Pll, input_freq: u32, config: PllConfig) -> u32 {
     vco_freq / ((config.post_div1 * config.post_div2) as u32)
 }
 
+/// General purpose input clock pin.
 pub trait GpinPin: crate::gpio::Pin {
+    /// Pin number.
     const NR: usize;
 }
 
@@ -697,12 +787,14 @@ macro_rules! impl_gpinpin {
 impl_gpinpin!(PIN_20, 20, 0);
 impl_gpinpin!(PIN_22, 22, 1);
 
+/// General purpose clock input driver.
 pub struct Gpin<'d, T: Pin> {
     gpin: PeripheralRef<'d, AnyPin>,
     _phantom: PhantomData<T>,
 }
 
 impl<'d, T: Pin> Gpin<'d, T> {
+    /// Create new gpin driver.
     pub fn new<P: GpinPin>(gpin: impl Peripheral<P = P> + 'd) -> Gpin<'d, P> {
         into_ref!(gpin);
 
@@ -728,7 +820,9 @@ impl<'d, T: Pin> Drop for Gpin<'d, T> {
     }
 }
 
+/// General purpose clock output pin.
 pub trait GpoutPin: crate::gpio::Pin {
+    /// Pin number.
     fn number(&self) -> usize;
 }
 
@@ -747,26 +841,38 @@ impl_gpoutpin!(PIN_23, 1);
 impl_gpoutpin!(PIN_24, 2);
 impl_gpoutpin!(PIN_25, 3);
 
+/// Gpout clock source.
 #[repr(u8)]
 pub enum GpoutSrc {
+    /// Sys PLL.
     PllSys = ClkGpoutCtrlAuxsrc::CLKSRC_PLL_SYS as _,
     // Gpin0 = ClkGpoutCtrlAuxsrc::CLKSRC_GPIN0 as _ ,
     // Gpin1 = ClkGpoutCtrlAuxsrc::CLKSRC_GPIN1 as _ ,
+    /// USB PLL.
     PllUsb = ClkGpoutCtrlAuxsrc::CLKSRC_PLL_USB as _,
+    /// ROSC.
     Rosc = ClkGpoutCtrlAuxsrc::ROSC_CLKSRC as _,
+    /// XOSC.
     Xosc = ClkGpoutCtrlAuxsrc::XOSC_CLKSRC as _,
+    /// SYS.
     Sys = ClkGpoutCtrlAuxsrc::CLK_SYS as _,
+    /// USB.
     Usb = ClkGpoutCtrlAuxsrc::CLK_USB as _,
+    /// ADC.
     Adc = ClkGpoutCtrlAuxsrc::CLK_ADC as _,
+    /// RTC.
     Rtc = ClkGpoutCtrlAuxsrc::CLK_RTC as _,
+    /// REF.
     Ref = ClkGpoutCtrlAuxsrc::CLK_REF as _,
 }
 
+/// General purpose clock output driver.
 pub struct Gpout<'d, T: GpoutPin> {
     gpout: PeripheralRef<'d, T>,
 }
 
 impl<'d, T: GpoutPin> Gpout<'d, T> {
+    /// Create new general purpose cloud output.
     pub fn new(gpout: impl Peripheral<P = T> + 'd) -> Self {
         into_ref!(gpout);
 
@@ -775,6 +881,7 @@ impl<'d, T: GpoutPin> Gpout<'d, T> {
         Self { gpout }
     }
 
+    /// Set clock divider.
     pub fn set_div(&self, int: u32, frac: u8) {
         let c = pac::CLOCKS;
         c.clk_gpout_div(self.gpout.number()).write(|w| {
@@ -783,6 +890,7 @@ impl<'d, T: GpoutPin> Gpout<'d, T> {
         });
     }
 
+    /// Set clock source.
     pub fn set_src(&self, src: GpoutSrc) {
         let c = pac::CLOCKS;
         c.clk_gpout_ctrl(self.gpout.number()).modify(|w| {
@@ -790,6 +898,7 @@ impl<'d, T: GpoutPin> Gpout<'d, T> {
         });
     }
 
+    /// Enable clock.
     pub fn enable(&self) {
         let c = pac::CLOCKS;
         c.clk_gpout_ctrl(self.gpout.number()).modify(|w| {
@@ -797,6 +906,7 @@ impl<'d, T: GpoutPin> Gpout<'d, T> {
         });
     }
 
+    /// Disable clock.
     pub fn disable(&self) {
         let c = pac::CLOCKS;
         c.clk_gpout_ctrl(self.gpout.number()).modify(|w| {
@@ -804,6 +914,7 @@ impl<'d, T: GpoutPin> Gpout<'d, T> {
         });
     }
 
+    /// Clock frequency.
     pub fn get_freq(&self) -> u32 {
         let c = pac::CLOCKS;
         let src = c.clk_gpout_ctrl(self.gpout.number()).read().auxsrc();

embassy-rp/src/dma.rs

@@ -38,6 +38,9 @@ pub(crate) unsafe fn init() {
     interrupt::DMA_IRQ_0.enable();
 }
 
+/// DMA read.
+///
+/// SAFETY: Slice must point to a valid location reachable by DMA.
 pub unsafe fn read<'a, C: Channel, W: Word>(
     ch: impl Peripheral<P = C> + 'a,
     from: *const W,
@@ -57,6 +60,9 @@ pub unsafe fn read<'a, C: Channel, W: Word>(
     )
 }
 
+/// DMA write.
+///
+/// SAFETY: Slice must point to a valid location reachable by DMA.
 pub unsafe fn write<'a, C: Channel, W: Word>(
     ch: impl Peripheral<P = C> + 'a,
     from: *const [W],
@@ -79,6 +85,9 @@ pub unsafe fn write<'a, C: Channel, W: Word>(
 // static mut so that this is allocated in RAM.
 static mut DUMMY: u32 = 0;
 
+/// DMA repeated write.
+///
+/// SAFETY: Slice must point to a valid location reachable by DMA.
 pub unsafe fn write_repeated<'a, C: Channel, W: Word>(
     ch: impl Peripheral<P = C> + 'a,
     to: *mut W,
@@ -97,6 +106,9 @@ pub unsafe fn write_repeated<'a, C: Channel, W: Word>(
     )
 }
 
+/// DMA copy between slices.
+///
+/// SAFETY: Slices must point to locations reachable by DMA.
 pub unsafe fn copy<'a, C: Channel, W: Word>(
     ch: impl Peripheral<P = C> + 'a,
     from: &[W],
@@ -152,6 +164,7 @@ fn copy_inner<'a, C: Channel>(
     Transfer::new(ch)
 }
 
+/// DMA transfer driver.
 #[must_use = "futures do nothing unless you `.await` or poll them"]
 pub struct Transfer<'a, C: Channel> {
     channel: PeripheralRef<'a, C>,
@@ -201,19 +214,25 @@ mod sealed {
     pub trait Word {}
 }
 
+/// DMA channel interface.
 pub trait Channel: Peripheral<P = Self> + sealed::Channel + Into<AnyChannel> + Sized + 'static {
+    /// Channel number.
     fn number(&self) -> u8;
 
+    /// Channel registry block.
     fn regs(&self) -> pac::dma::Channel {
         pac::DMA.ch(self.number() as _)
     }
 
+    /// Convert into type-erased [AnyChannel].
     fn degrade(self) -> AnyChannel {
         AnyChannel { number: self.number() }
     }
 }
 
+/// DMA word.
 pub trait Word: sealed::Word {
+    /// Word size.
     fn size() -> vals::DataSize;
 }
 
@@ -238,6 +257,7 @@ impl Word for u32 {
     }
 }
 
+/// Type erased DMA channel.
 pub struct AnyChannel {
     number: u8,
 }

embassy-rp/src/flash.rs

@@ -1,3 +1,4 @@
+//! Flash driver.
 use core::future::Future;
 use core::marker::PhantomData;
 use core::pin::Pin;
@@ -13,9 +14,10 @@ use crate::dma::{AnyChannel, Channel, Transfer};
 use crate::pac;
 use crate::peripherals::FLASH;
 
+/// Flash base address.
 pub const FLASH_BASE: *const u32 = 0x10000000 as _;
 
-// If running from RAM, we might have no boot2. Use bootrom `flash_enter_cmd_xip` instead.
+/// If running from RAM, we might have no boot2. Use bootrom `flash_enter_cmd_xip` instead.
 // TODO: when run-from-ram is set, completely skip the "pause cores and jumpp to RAM" dance.
 pub const USE_BOOT2: bool = !cfg!(feature = "run-from-ram");
 
@@ -24,10 +26,15 @@ pub const USE_BOOT2: bool = !cfg!(feature = "run-from-ram");
 // These limitations are currently enforced because of using the
 // RP2040 boot-rom flash functions, that are optimized for flash compatibility
 // rather than performance.
+/// Flash page size.
 pub const PAGE_SIZE: usize = 256;
+/// Flash write size.
 pub const WRITE_SIZE: usize = 1;
+/// Flash read size.
 pub const READ_SIZE: usize = 1;
+/// Flash erase size.
 pub const ERASE_SIZE: usize = 4096;
+/// Flash DMA read size.
 pub const ASYNC_READ_SIZE: usize = 4;
 
 /// Error type for NVMC operations.
@@ -38,7 +45,9 @@ pub enum Error {
     OutOfBounds,
     /// Unaligned operation or using unaligned buffers.
     Unaligned,
+    /// Accessed from the wrong core.
     InvalidCore,
+    /// Other error
     Other,
 }
 
@@ -96,12 +105,18 @@ impl<'a, 'd, T: Instance, const FLASH_SIZE: usize> Drop for BackgroundRead<'a, '
     }
 }
 
+/// Flash driver.
 pub struct Flash<'d, T: Instance, M: Mode, const FLASH_SIZE: usize> {
     dma: Option<PeripheralRef<'d, AnyChannel>>,
     phantom: PhantomData<(&'d mut T, M)>,
 }
 
 impl<'d, T: Instance, M: Mode, const FLASH_SIZE: usize> Flash<'d, T, M, FLASH_SIZE> {
+    /// Blocking read.
+    ///
+    /// The offset and buffer must be aligned.
+    ///
+    /// NOTE: `offset` is an offset from the flash start, NOT an absolute address.
     pub fn blocking_read(&mut self, offset: u32, bytes: &mut [u8]) -> Result<(), Error> {
         trace!(
             "Reading from 0x{:x} to 0x{:x}",
@@ -116,10 +131,14 @@ impl<'d, T: Instance, M: Mode, const FLASH_SIZE: usize> Flash<'d, T, M, FLASH_SI
         Ok(())
     }
 
+    /// Flash capacity.
     pub fn capacity(&self) -> usize {
         FLASH_SIZE
     }
 
+    /// Blocking erase.
+    ///
+    /// NOTE: `offset` is an offset from the flash start, NOT an absolute address.
     pub fn blocking_erase(&mut self, from: u32, to: u32) -> Result<(), Error> {
         check_erase(self, from, to)?;
 
@@ -136,6 +155,11 @@ impl<'d, T: Instance, M: Mode, const FLASH_SIZE: usize> Flash<'d, T, M, FLASH_SI
         Ok(())
     }
 
+    /// Blocking write.
+    ///
+    /// The offset and buffer must be aligned.
+    ///
+    /// NOTE: `offset` is an offset from the flash start, NOT an absolute address.
     pub fn blocking_write(&mut self, offset: u32, bytes: &[u8]) -> Result<(), Error> {
         check_write(self, offset, bytes.len())?;
 
@@ -219,6 +243,7 @@ impl<'d, T: Instance, M: Mode, const FLASH_SIZE: usize> Flash<'d, T, M, FLASH_SI
 }
 
 impl<'d, T: Instance, const FLASH_SIZE: usize> Flash<'d, T, Blocking, FLASH_SIZE> {
+    /// Create a new flash driver in blocking mode.
     pub fn new_blocking(_flash: impl Peripheral<P = T> + 'd) -> Self {
         Self {
             dma: None,
@@ -228,6 +253,7 @@ impl<'d, T: Instance, const FLASH_SIZE: usize> Flash<'d, T, Blocking, FLASH_SIZE
 }
 
 impl<'d, T: Instance, const FLASH_SIZE: usize> Flash<'d, T, Async, FLASH_SIZE> {
+    /// Create a new flash driver in async mode.
     pub fn new(_flash: impl Peripheral<P = T> + 'd, dma: impl Peripheral<P = impl Channel> + 'd) -> Self {
         into_ref!(dma);
         Self {
@@ -236,6 +262,11 @@ impl<'d, T: Instance, const FLASH_SIZE: usize> Flash<'d, T, Async, FLASH_SIZE> {
         }
     }
 
+    /// Start a background read operation.
+    ///
+    /// The offset and buffer must be aligned.
+    ///
+    /// NOTE: `offset` is an offset from the flash start, NOT an absolute address.
     pub fn background_read<'a>(
         &'a mut self,
         offset: u32,
@@ -279,6 +310,11 @@ impl<'d, T: Instance, const FLASH_SIZE: usize> Flash<'d, T, Async, FLASH_SIZE> {
         })
     }
 
+    /// Async read.
+    ///
+    /// The offset and buffer must be aligned.
+    ///
+    /// NOTE: `offset` is an offset from the flash start, NOT an absolute address.
     pub async fn read(&mut self, offset: u32, bytes: &mut [u8]) -> Result<(), Error> {
         use core::mem::MaybeUninit;
 
@@ -874,7 +910,9 @@ mod sealed {
     pub trait Mode {}
 }
 
+/// Flash instance.
 pub trait Instance: sealed::Instance {}
+/// Flash mode.
 pub trait Mode: sealed::Mode {}
 
 impl sealed::Instance for FLASH {}
@@ -887,7 +925,9 @@ macro_rules! impl_mode {
     };
 }
 
+/// Flash blocking mode.
 pub struct Blocking;
+/// Flash async mode.
 pub struct Async;
 
 impl_mode!(Blocking);

embassy-rp/src/gpio.rs

@@ -1,3 +1,4 @@
+//! GPIO driver.
 #![macro_use]
 use core::convert::Infallible;
 use core::future::Future;
@@ -23,7 +24,9 @@ static QSPI_WAKERS: [AtomicWaker; QSPI_PIN_COUNT] = [NEW_AW; QSPI_PIN_COUNT];
 /// Represents a digital input or output level.
 #[derive(Debug, Eq, PartialEq, Clone, Copy)]
 pub enum Level {
+    /// Logical low.
     Low,
+    /// Logical high.
     High,
 }
 
@@ -48,48 +51,66 @@ impl From<Level> for bool {
 /// Represents a pull setting for an input.
 #[derive(Debug, Clone, Copy, Eq, PartialEq)]
 pub enum Pull {
+    /// No pull.
     None,
+    /// Internal pull-up resistor.
     Up,
+    /// Internal pull-down resistor.
     Down,
 }
 
 /// Drive strength of an output
 #[derive(Debug, Eq, PartialEq)]
 pub enum Drive {
+    /// 2 mA drive.
     _2mA,
+    /// 4 mA drive.
     _4mA,
+    /// 8 mA drive.
     _8mA,
+    /// 1 2mA drive.
     _12mA,
 }
 /// Slew rate of an output
 #[derive(Debug, Eq, PartialEq)]
 pub enum SlewRate {
+    /// Fast slew rate.
     Fast,
+    /// Slow slew rate.
     Slow,
 }
 
 /// A GPIO bank with up to 32 pins.
 #[derive(Debug, Eq, PartialEq)]
 pub enum Bank {
+    /// Bank 0.
     Bank0 = 0,
+    /// QSPI.
     #[cfg(feature = "qspi-as-gpio")]
     Qspi = 1,
 }
 
+/// Dormant mode config.
 #[derive(Debug, Eq, PartialEq, Copy, Clone, Default)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub struct DormantWakeConfig {
+    /// Wake on edge high.
     pub edge_high: bool,
+    /// Wake on edge low.
     pub edge_low: bool,
+    /// Wake on level high.
     pub level_high: bool,
+    /// Wake on level low.
     pub level_low: bool,
 }
 
+/// GPIO input driver.
 pub struct Input<'d, T: Pin> {
     pin: Flex<'d, T>,
 }
 
 impl<'d, T: Pin> Input<'d, T> {
+    /// Create GPIO input driver for a [Pin] with the provided [Pull] configuration.
     #[inline]
     pub fn new(pin: impl Peripheral<P = T> + 'd, pull: Pull) -> Self {
         let mut pin = Flex::new(pin);
@@ -104,11 +125,13 @@ impl<'d, T: Pin> Input<'d, T> {
         self.pin.set_schmitt(enable)
     }
 
+    /// Get whether the pin input level is high.
     #[inline]
     pub fn is_high(&mut self) -> bool {
         self.pin.is_high()
     }
 
+    /// Get whether the pin input level is low.
     #[inline]
     pub fn is_low(&mut self) -> bool {
         self.pin.is_low()
@@ -120,31 +143,37 @@ impl<'d, T: Pin> Input<'d, T> {
         self.pin.get_level()
     }
 
+    /// Wait until the pin is high. If it is already high, return immediately.
     #[inline]
     pub async fn wait_for_high(&mut self) {
         self.pin.wait_for_high().await;
     }
 
+    /// Wait until the pin is low. If it is already low, return immediately.
     #[inline]
     pub async fn wait_for_low(&mut self) {
         self.pin.wait_for_low().await;
     }
 
+    /// Wait for the pin to undergo a transition from low to high.
     #[inline]
     pub async fn wait_for_rising_edge(&mut self) {
         self.pin.wait_for_rising_edge().await;
     }
 
+    /// Wait for the pin to undergo a transition from high to low.
     #[inline]
     pub async fn wait_for_falling_edge(&mut self) {
         self.pin.wait_for_falling_edge().await;
     }
 
+    /// Wait for the pin to undergo any transition, i.e low to high OR high to low.
     #[inline]
     pub async fn wait_for_any_edge(&mut self) {
         self.pin.wait_for_any_edge().await;
     }
 
+    /// Configure dormant wake.
     #[inline]
     pub fn dormant_wake(&mut self, cfg: DormantWakeConfig) -> DormantWake<T> {
         self.pin.dormant_wake(cfg)
@@ -155,10 +184,15 @@ impl<'d, T: Pin> Input<'d, T> {
 #[derive(Debug, Eq, PartialEq, Copy, Clone)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum InterruptTrigger {
+    /// Trigger on pin low.
     LevelLow,
+    /// Trigger on pin high.
     LevelHigh,
+    /// Trigger on high to low transition.
     EdgeLow,
+    /// Trigger on low to high transition.
     EdgeHigh,
+    /// Trigger on any transition.
     AnyEdge,
 }
 
@@ -226,6 +260,7 @@ struct InputFuture<'a, T: Pin> {
 }
 
 impl<'d, T: Pin> InputFuture<'d, T> {
+    /// Create a new future wiating for input trigger.
     pub fn new(pin: impl Peripheral<P = T> + 'd, level: InterruptTrigger) -> Self {
         into_ref!(pin);
         let pin_group = (pin.pin() % 8) as usize;
@@ -308,11 +343,13 @@ impl<'d, T: Pin> Future for InputFuture<'d, T> {
     }
 }
 
+/// GPIO output driver.
 pub struct Output<'d, T: Pin> {
     pin: Flex<'d, T>,
 }
 
 impl<'d, T: Pin> Output<'d, T> {
+    /// Create GPIO output driver for a [Pin] with the provided [Level].
     #[inline]
     pub fn new(pin: impl Peripheral<P = T> + 'd, initial_output: Level) -> Self {
         let mut pin = Flex::new(pin);
@@ -331,7 +368,7 @@ impl<'d, T: Pin> Output<'d, T> {
         self.pin.set_drive_strength(strength)
     }
 
-    // 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.set_slew_rate(slew_rate)
@@ -386,6 +423,7 @@ pub struct OutputOpenDrain<'d, T: Pin> {
 }
 
 impl<'d, T: Pin> OutputOpenDrain<'d, T> {
+    /// Create GPIO output driver for a [Pin] in open drain mode with the provided [Level].
     #[inline]
     pub fn new(pin: impl Peripheral<P = T> + 'd, initial_output: Level) -> Self {
         let mut pin = Flex::new(pin);
@@ -403,7 +441,7 @@ impl<'d, T: Pin> OutputOpenDrain<'d, T> {
         self.pin.set_drive_strength(strength)
     }
 
-    // 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.set_slew_rate(slew_rate)
@@ -456,11 +494,13 @@ impl<'d, T: Pin> OutputOpenDrain<'d, T> {
         self.pin.toggle_set_as_output()
     }
 
+    /// Get whether the pin input level is high.
     #[inline]
     pub fn is_high(&mut self) -> bool {
         self.pin.is_high()
     }
 
+    /// Get whether the pin input level is low.
     #[inline]
     pub fn is_low(&mut self) -> bool {
         self.pin.is_low()
@@ -472,26 +512,31 @@ impl<'d, T: Pin> OutputOpenDrain<'d, T> {
         self.is_high().into()
     }
 
+    /// Wait until the pin is high. If it is already high, return immediately.
     #[inline]
     pub async fn wait_for_high(&mut self) {
         self.pin.wait_for_high().await;
     }
 
+    /// Wait until the pin is low. If it is already low, return immediately.
     #[inline]
     pub async fn wait_for_low(&mut self) {
         self.pin.wait_for_low().await;
     }
 
+    /// Wait for the pin to undergo a transition from low to high.
     #[inline]
     pub async fn wait_for_rising_edge(&mut self) {
         self.pin.wait_for_rising_edge().await;
     }
 
+    /// Wait for the pin to undergo a transition from high to low.
     #[inline]
     pub async fn wait_for_falling_edge(&mut self) {
         self.pin.wait_for_falling_edge().await;
     }
 
+    /// Wait for the pin to undergo any transition, i.e low to high OR high to low.
     #[inline]
     pub async fn wait_for_any_edge(&mut self) {
         self.pin.wait_for_any_edge().await;
@@ -508,6 +553,10 @@ pub struct Flex<'d, T: Pin> {
 }
 
 impl<'d, T: Pin> Flex<'d, T> {
+    /// Wrap the pin in a `Flex`.
+    ///
+    /// The pin remains disconnected. The initial output level is unspecified, but can be changed
+    /// before the pin is put into output mode.
     #[inline]
     pub fn new(pin: impl Peripheral<P = T> + 'd) -> Self {
         into_ref!(pin);
@@ -556,7 +605,7 @@ impl<'d, T: Pin> Flex<'d, T> {
         });
     }
 
-    // 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| {
@@ -589,6 +638,7 @@ impl<'d, T: Pin> Flex<'d, T> {
         self.pin.sio_oe().value_set().write_value(self.bit())
     }
 
+    /// Set as output pin.
     #[inline]
     pub fn is_set_as_output(&mut self) -> bool {
         self.ref_is_set_as_output()
@@ -599,15 +649,18 @@ impl<'d, T: Pin> Flex<'d, T> {
         (self.pin.sio_oe().value().read() & self.bit()) != 0
     }
 
+    /// Toggle output pin.
     #[inline]
     pub fn toggle_set_as_output(&mut self) {
         self.pin.sio_oe().value_xor().write_value(self.bit())
     }
 
+    /// Get whether the pin input level is high.
     #[inline]
     pub fn is_high(&mut self) -> bool {
         !self.is_low()
     }
+    /// Get whether the pin input level is low.
 
     #[inline]
     pub fn is_low(&mut self) -> bool {
@@ -675,31 +728,37 @@ impl<'d, T: Pin> Flex<'d, T> {
         self.pin.sio_out().value_xor().write_value(self.bit())
     }
 
+    /// Wait until the pin is high. If it is already high, return immediately.
     #[inline]
     pub async fn wait_for_high(&mut self) {
         InputFuture::new(&mut self.pin, InterruptTrigger::LevelHigh).await;
     }
 
+    /// Wait until the pin is low. If it is already low, return immediately.
     #[inline]
     pub async fn wait_for_low(&mut self) {
         InputFuture::new(&mut self.pin, InterruptTrigger::LevelLow).await;
     }
 
+    /// Wait for the pin to undergo a transition from low to high.
     #[inline]
     pub async fn wait_for_rising_edge(&mut self) {
         InputFuture::new(&mut self.pin, InterruptTrigger::EdgeHigh).await;
     }
 
+    /// Wait for the pin to undergo a transition from high to low.
     #[inline]
     pub async fn wait_for_falling_edge(&mut self) {
         InputFuture::new(&mut self.pin, InterruptTrigger::EdgeLow).await;
     }
 
+    /// Wait for the pin to undergo any transition, i.e low to high OR high to low.
     #[inline]
     pub async fn wait_for_any_edge(&mut self) {
         InputFuture::new(&mut self.pin, InterruptTrigger::AnyEdge).await;
     }
 
+    /// Configure dormant wake.
     #[inline]
     pub fn dormant_wake(&mut self, cfg: DormantWakeConfig) -> DormantWake<T> {
         let idx = self.pin._pin() as usize;
@@ -737,6 +796,7 @@ impl<'d, T: Pin> Drop for Flex<'d, T> {
     }
 }
 
+/// Dormant wake driver.
 pub struct DormantWake<'w, T: Pin> {
     pin: PeripheralRef<'w, T>,
     cfg: DormantWakeConfig,
@@ -818,6 +878,7 @@ pub(crate) mod sealed {
     }
 }
 
+/// Interface for a Pin that can be configured by an [Input] or [Output] driver, or converted to an [AnyPin].
 pub trait Pin: Peripheral<P = Self> + Into<AnyPin> + sealed::Pin + Sized + 'static {
     /// Degrade to a generic pin struct
     fn degrade(self) -> AnyPin {
@@ -839,6 +900,7 @@ pub trait Pin: Peripheral<P = Self> + Into<AnyPin> + sealed::Pin + Sized + 'stat
     }
 }
 
+/// Type-erased GPIO pin
 pub struct AnyPin {
     pin_bank: u8,
 }

embassy-rp/src/i2c.rs

@@ -1,3 +1,4 @@
+//! I2C driver.
 use core::future;
 use core::marker::PhantomData;
 use core::task::Poll;
@@ -22,6 +23,7 @@ pub enum AbortReason {
     ArbitrationLoss,
     /// Transmit ended with data still in fifo
     TxNotEmpty(u16),
+    /// Other reason.
     Other(u32),
 }
 
@@ -41,9 +43,11 @@ pub enum Error {
     AddressReserved(u16),
 }
 
+/// I2C config.
 #[non_exhaustive]
 #[derive(Copy, Clone)]
 pub struct Config {
+    /// Frequency.
     pub frequency: u32,
 }
 
@@ -53,13 +57,16 @@ impl Default for Config {
     }
 }
 
+/// Size of I2C FIFO.
 pub const FIFO_SIZE: u8 = 16;
 
+/// I2C driver.
 pub struct I2c<'d, T: Instance, M: Mode> {
     phantom: PhantomData<(&'d mut T, M)>,
 }
 
 impl<'d, T: Instance> I2c<'d, T, Blocking> {
+    /// Create a new driver instance in blocking mode.
     pub fn new_blocking(
         peri: impl Peripheral<P = T> + 'd,
         scl: impl Peripheral<P = impl SclPin<T>> + 'd,
@@ -72,6 +79,7 @@ impl<'d, T: Instance> I2c<'d, T, Blocking> {
 }
 
 impl<'d, T: Instance> I2c<'d, T, Async> {
+    /// Create a new driver instance in async mode.
     pub fn new_async(
         peri: impl Peripheral<P = T> + 'd,
         scl: impl Peripheral<P = impl SclPin<T>> + 'd,
@@ -292,16 +300,19 @@ impl<'d, T: Instance> I2c<'d, T, Async> {
         }
     }
 
+    /// Read from address into buffer using DMA.
     pub async fn read_async(&mut self, addr: u16, buffer: &mut [u8]) -> Result<(), Error> {
         Self::setup(addr)?;
         self.read_async_internal(buffer, true, true).await
     }
 
+    /// Write to address from buffer using DMA.
     pub async fn write_async(&mut self, addr: u16, bytes: impl IntoIterator<Item = u8>) -> Result<(), Error> {
         Self::setup(addr)?;
         self.write_async_internal(bytes, true).await
     }
 
+    /// Write to address from bytes and read from address into buffer using DMA.
     pub async fn write_read_async(
         &mut self,
         addr: u16,
@@ -314,6 +325,7 @@ impl<'d, T: Instance> I2c<'d, T, Async> {
     }
 }
 
+/// Interrupt handler.
 pub struct InterruptHandler<T: Instance> {
     _uart: PhantomData<T>,
 }
@@ -569,17 +581,20 @@ impl<'d, T: Instance + 'd, M: Mode> I2c<'d, T, M> {
     // Blocking public API
     // =========================
 
+    /// Read from address into buffer blocking caller until done.
     pub fn blocking_read(&mut self, address: u8, read: &mut [u8]) -> Result<(), Error> {
         Self::setup(address.into())?;
         self.read_blocking_internal(read, true, true)
         // Automatic Stop
     }
 
+    /// Write to address from buffer blocking caller until done.
     pub fn blocking_write(&mut self, address: u8, write: &[u8]) -> Result<(), Error> {
         Self::setup(address.into())?;
         self.write_blocking_internal(write, true)
     }
 
+    /// Write to address from bytes and read from address into buffer blocking caller until done.
     pub fn blocking_write_read(&mut self, address: u8, write: &[u8], read: &mut [u8]) -> Result<(), Error> {
         Self::setup(address.into())?;
         self.write_blocking_internal(write, false)?;
@@ -742,6 +757,7 @@ where
     }
 }
 
+/// Check if address is reserved.
 pub fn i2c_reserved_addr(addr: u16) -> bool {
     ((addr & 0x78) == 0 || (addr & 0x78) == 0x78) && addr != 0
 }
@@ -768,6 +784,7 @@ mod sealed {
     pub trait SclPin<T: Instance> {}
 }
 
+/// Driver mode.
 pub trait Mode: sealed::Mode {}
 
 macro_rules! impl_mode {
@@ -777,12 +794,15 @@ macro_rules! impl_mode {
     };
 }
 
+/// Blocking mode.
 pub struct Blocking;
+/// Async mode.
 pub struct Async;
 
 impl_mode!(Blocking);
 impl_mode!(Async);
 
+/// I2C instance.
 pub trait Instance: sealed::Instance {}
 
 macro_rules! impl_instance {
@@ -819,7 +839,9 @@ macro_rules! impl_instance {
 impl_instance!(I2C0, I2C0_IRQ, set_i2c0, 32, 33);
 impl_instance!(I2C1, I2C1_IRQ, set_i2c1, 34, 35);
 
+/// SDA pin.
 pub trait SdaPin<T: Instance>: sealed::SdaPin<T> + crate::gpio::Pin {}
+/// SCL pin.
 pub trait SclPin<T: Instance>: sealed::SclPin<T> + crate::gpio::Pin {}
 
 macro_rules! impl_pin {

embassy-rp/src/i2c_slave.rs

@@ -1,3 +1,4 @@
+//! I2C slave driver.
 use core::future;
 use core::marker::PhantomData;
 use core::task::Poll;
@@ -63,11 +64,13 @@ impl Default for Config {
     }
 }
 
+/// I2CSlave driver.
 pub struct I2cSlave<'d, T: Instance> {
     phantom: PhantomData<&'d mut T>,
 }
 
 impl<'d, T: Instance> I2cSlave<'d, T> {
+    /// Create a new instance.
     pub fn new(
         _peri: impl Peripheral<P = T> + 'd,
         scl: impl Peripheral<P = impl SclPin<T>> + 'd,

embassy-rp/src/lib.rs

@@ -1,5 +1,7 @@
 #![no_std]
 #![allow(async_fn_in_trait)]
+#![doc = include_str!("../README.md")]
+#![warn(missing_docs)]
 
 // This mod MUST go first, so that the others see its macros.
 pub(crate) mod fmt;
@@ -31,9 +33,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 +302,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 +322,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

@@ -1,3 +1,4 @@
+//! PIO driver.
 use core::future::Future;
 use core::marker::PhantomData;
 use core::pin::Pin as FuturePin;
@@ -19,8 +20,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 +42,7 @@ impl Wakers {
     }
 }
 
+/// FIFO config.
 #[derive(Clone, Copy, PartialEq, Eq, Default, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[repr(u8)]
@@ -51,6 +56,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 +67,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 +77,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 +93,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 +118,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 +150,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 +222,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 +242,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 +267,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 +277,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 +314,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 +324,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 +337,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 +368,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 +399,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 +409,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 +423,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 +450,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 +470,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 +571,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 +609,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 +644,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 +691,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 +700,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 +716,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 +769,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 +781,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 +817,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 +931,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 +940,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 +960,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 +978,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 +988,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>) {
+    /// Restart a state machine's clock divider from an initial phase of 0.
-        self.clkdiv_restart |= 1 << SM;
-    }
-
     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 +1015,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 +1124,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
+/// Representation of the PIO state keeping a record of which pins are assigned to
-// notionally takes ownership of the pin it is given, but the wrapped pin cannot
+/// each PIO.
-// be treated as an owned resource since dropping it would have to deconfigure
+// 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 +1181,7 @@ mod sealed {
     }
 }
 
+/// PIO instance.
 pub trait Instance: sealed::Instance + Sized + Unpin {}
 
 macro_rules! impl_pio {
@@ -1076,6 +1199,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>>,
@@ -114,11 +119,13 @@ impl<'d, T: Channel> Pwm<'d, T> {
         }
     }
 
+    /// Create PWM driver without any configured pins.
     #[inline]
     pub fn new_free(inner: impl Peripheral<P = T> + 'd, config: Config) -> Self {
         Self::new_inner(inner, None, None, config, Divmode::DIV)
     }
 
+    /// Create PWM driver with a single 'a' as output.
     #[inline]
     pub fn new_output_a(
         inner: impl Peripheral<P = T> + 'd,
@@ -129,6 +136,7 @@ impl<'d, T: Channel> Pwm<'d, T> {
         Self::new_inner(inner, Some(a.map_into()), None, config, Divmode::DIV)
     }
 
+    /// Create PWM driver with a single 'b' pin as output.
     #[inline]
     pub fn new_output_b(
         inner: impl Peripheral<P = T> + 'd,
@@ -139,6 +147,7 @@ impl<'d, T: Channel> Pwm<'d, T> {
         Self::new_inner(inner, None, Some(b.map_into()), config, Divmode::DIV)
     }
 
+    /// Create PWM driver with a 'a' and 'b' pins as output.
     #[inline]
     pub fn new_output_ab(
         inner: impl Peripheral<P = T> + 'd,
@@ -150,6 +159,7 @@ impl<'d, T: Channel> Pwm<'d, T> {
         Self::new_inner(inner, Some(a.map_into()), Some(b.map_into()), config, Divmode::DIV)
     }
 
+    /// Create PWM driver with a single 'b' as input pin.
     #[inline]
     pub fn new_input(
         inner: impl Peripheral<P = T> + 'd,
@@ -161,6 +171,7 @@ impl<'d, T: Channel> Pwm<'d, T> {
         Self::new_inner(inner, None, Some(b.map_into()), config, mode.into())
     }
 
+    /// Create PWM driver with a 'a' and 'b' pins in the desired input mode.
     #[inline]
     pub fn new_output_input(
         inner: impl Peripheral<P = T> + 'd,
@@ -173,6 +184,7 @@ impl<'d, T: Channel> Pwm<'d, T> {
         Self::new_inner(inner, Some(a.map_into()), Some(b.map_into()), config, mode.into())
     }
 
+    /// Set the PWM config.
     pub fn set_config(&mut self, config: &Config) {
         Self::configure(self.inner.regs(), config);
     }
@@ -216,28 +228,33 @@ impl<'d, T: Channel> Pwm<'d, T> {
         while p.csr().read().ph_ret() {}
     }
 
+    /// Read PWM counter.
     #[inline]
     pub fn counter(&self) -> u16 {
         self.inner.regs().ctr().read().ctr()
     }
 
+    /// Write PWM counter.
     #[inline]
     pub fn set_counter(&self, ctr: u16) {
         self.inner.regs().ctr().write(|w| w.set_ctr(ctr))
     }
 
+    /// Wait for channel interrupt.
     #[inline]
     pub fn wait_for_wrap(&mut self) {
         while !self.wrapped() {}
         self.clear_wrapped();
     }
 
+    /// Check if interrupt for channel is set.
     #[inline]
     pub fn wrapped(&mut self) -> bool {
         pac::PWM.intr().read().0 & self.bit() != 0
     }
 
     #[inline]
+    /// Clear interrupt flag.
     pub fn clear_wrapped(&mut self) {
         pac::PWM.intr().write_value(Intr(self.bit() as _));
     }
@@ -248,15 +265,18 @@ impl<'d, T: Channel> Pwm<'d, T> {
     }
 }
 
+/// Batch representation of PWM channels.
 pub struct PwmBatch(u32);
 
 impl PwmBatch {
     #[inline]
+    /// Enable a PWM channel in this batch.
     pub fn enable(&mut self, pwm: &Pwm<'_, impl Channel>) {
         self.0 |= pwm.bit();
     }
 
     #[inline]
+    /// Enable channels in this batch in a PWM.
     pub fn set_enabled(enabled: bool, batch: impl FnOnce(&mut PwmBatch)) {
         let mut en = PwmBatch(0);
         batch(&mut en);
@@ -284,9 +304,12 @@ mod sealed {
     pub trait Channel {}
 }
 
+/// PWM Channel.
 pub trait Channel: Peripheral<P = Self> + sealed::Channel + Sized + 'static {
+    /// Channel number.
     fn number(&self) -> u8;
 
+    /// Channel register block.
     fn regs(&self) -> pac::pwm::Channel {
         pac::PWM.ch(self.number() as _)
     }
@@ -312,7 +335,9 @@ channel!(PWM_CH5, 5);
 channel!(PWM_CH6, 6);
 channel!(PWM_CH7, 7);
 
+/// PWM Pin A.
 pub trait PwmPinA<T: Channel>: GpioPin {}
+/// PWM Pin B.
 pub trait PwmPinB<T: Channel>: GpioPin {}
 
 macro_rules! impl_pin {

embassy-rp/src/rtc/mod.rs

@@ -1,3 +1,4 @@
+//! RTC driver.
 mod filter;
 
 use embassy_hal_internal::{into_ref, Peripheral, PeripheralRef};
@@ -194,6 +195,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/timer.rs

@@ -1,3 +1,4 @@
+//! Timer driver.
 use core::cell::Cell;
 
 use atomic_polyfill::{AtomicU8, Ordering};

embassy-rp/src/uart/buffered.rs

@@ -1,3 +1,4 @@
+//! Buffered UART driver.
 use core::future::{poll_fn, Future};
 use core::slice;
 use core::task::Poll;
@@ -38,15 +39,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 +88,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 +109,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 +138,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 +186,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 +267,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 +318,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 +334,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 +390,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 +416,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 +426,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 +486,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

@@ -1,3 +1,4 @@
+//! UART driver.
 use core::future::poll_fn;
 use core::marker::PhantomData;
 use core::task::Poll;
@@ -20,11 +21,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 +45,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 +65,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,31 +118,36 @@ pub enum Error {
     Framing,
 }
 
-/// Read To Break error
+/// Errors specific to `read_to_break()` functions
 #[derive(Debug, Eq, PartialEq, Copy, Clone)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[non_exhaustive]
 pub enum ReadToBreakError {
     /// Read this many bytes, but never received a line break.
     MissingBreak(usize),
+    /// A non-line-break related error occurred
     Other(Error),
 }
 
+/// 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)>,
@@ -152,6 +173,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 {
@@ -161,12 +183,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()
     }
@@ -201,6 +225,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>>,
@@ -213,6 +239,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 {
@@ -256,6 +283,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.is_empty() {
             let received = self.drain_fifo(buffer).map_err(|(_i, e)| e)?;
@@ -307,6 +335,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,
@@ -317,6 +346,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>>,
@@ -328,6 +359,7 @@ impl<'d, T: Instance> UartRx<'d, T, Blocking> {
     }
 }
 
+/// Interrupt handler.
 pub struct InterruptHandler<T: Instance> {
     _uart: PhantomData<T>,
 }
@@ -351,6 +383,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.
@@ -650,6 +683,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>>,
@@ -859,22 +894,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
     }
@@ -887,14 +927,19 @@ 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
     }
 
+    /// Read from the UART, waiting for a line break.
+    ///
+    /// See [`UartRx::read_to_break()`] for more details.
     pub async fn read_to_break<'a>(&mut self, buf: &'a mut [u8]) -> Result<usize, ReadToBreakError> {
         self.rx.read_to_break(buf).await
     }
@@ -1085,6 +1130,7 @@ mod sealed {
     pub trait RtsPin<T: Instance> {}
 }
 
+/// UART mode.
 pub trait Mode: sealed::Mode {}
 
 macro_rules! impl_mode {
@@ -1094,12 +1140,15 @@ macro_rules! impl_mode {
     };
 }
 
+/// Blocking mode.
 pub struct Blocking;
+/// Async mode.
 pub struct Async;
 
 impl_mode!(Blocking);
 impl_mode!(Async);
 
+/// UART instance.
 pub trait Instance: sealed::Instance {}
 
 macro_rules! impl_instance {
@@ -1134,9 +1183,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

@@ -1,3 +1,4 @@
+//! USB driver.
 use core::future::poll_fn;
 use core::marker::PhantomData;
 use core::slice;
@@ -20,7 +21,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 +99,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 +108,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 +245,7 @@ impl<'d, T: Instance> Driver<'d, T> {
     }
 }
 
+/// USB interrupt handler.
 pub struct InterruptHandler<T: Instance> {
     _uart: PhantomData<T>,
 }
@@ -342,6 +348,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 +468,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 +481,7 @@ impl Dir for In {
     }
 }
 
+/// Type for Out direction.
 pub enum Out {}
 impl Dir for Out {
     fn dir() -> Direction {
@@ -485,6 +494,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 +626,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/Cargo.toml

@@ -56,9 +56,8 @@ cortex-m = "0.7.6"
 futures = { version = "0.3.17", default-features = false, features = ["async-await"] }
 rand_core = "0.6.3"
 sdio-host = "0.5.0"
-embedded-sdmmc = { git = "https://github.com/embassy-rs/embedded-sdmmc-rs", rev = "a4f293d3a6f72158385f79c98634cb8a14d0d2fc", optional = true }
 critical-section = "1.1"
-stm32-metapac = { git = "https://github.com/embassy-rs/stm32-data-generated", tag = "stm32-data-91cee0d1fdcb4e447b65a09756b506f4af91b7e2" }
+stm32-metapac = { git = "https://github.com/embassy-rs/stm32-data-generated", tag = "stm32-data-2234f380f51d16d0398b8e547088b33ea623cc7c" }
 vcell = "0.1.3"
 bxcan = "0.7.0"
 nb = "1.0.0"
@@ -76,7 +75,7 @@ critical-section = { version = "1.1", features = ["std"] }
 [build-dependencies]
 proc-macro2 = "1.0.36"
 quote = "1.0.15"
-stm32-metapac = { git = "https://github.com/embassy-rs/stm32-data-generated", tag = "stm32-data-91cee0d1fdcb4e447b65a09756b506f4af91b7e2", default-features = false, features = ["metadata"]}
+stm32-metapac = { git = "https://github.com/embassy-rs/stm32-data-generated", tag = "stm32-data-2234f380f51d16d0398b8e547088b33ea623cc7c", default-features = false, features = ["metadata"]}
 
 
 [features]

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_A"), quote!(crate::sai::SckPin<A>)),
-        (("sai", "SCK_B"), quote!(crate::sai::SckBPin)),
+        (("sai", "SCK_B"), quote!(crate::sai::SckPin<B>)),
-        (("sai", "FS_A"), quote!(crate::sai::FsAPin)),
+        (("sai", "FS_A"), quote!(crate::sai::FsPin<A>)),
-        (("sai", "FS_B"), quote!(crate::sai::FsBPin)),
+        (("sai", "FS_B"), quote!(crate::sai::FsPin<B>)),
-        (("sai", "SD_A"), quote!(crate::sai::SdAPin)),
+        (("sai", "SD_A"), quote!(crate::sai::SdPin<A>)),
-        (("sai", "SD_B"), quote!(crate::sai::SdBPin)),
+        (("sai", "SD_B"), quote!(crate::sai::SdPin<B>)),
-        (("sai", "MCLK_A"), quote!(crate::sai::MclkAPin)),
+        (("sai", "MCLK_A"), quote!(crate::sai::MclkPin<A>)),
-        (("sai", "MCLK_B"), quote!(crate::sai::MclkBPin)),
+        (("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", "A"), quote!(crate::sai::Dma<A>)),
-        (("sai", "B"), quote!(crate::sai::DmaB)),
+        (("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,4 +1,5 @@
-//! Analog to Digital (ADC) converter driver.
+//! Analog to Digital Converter (ADC)
+
 #![macro_use]
 #![allow(missing_docs)] // TODO
 

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/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/bdma.rs

@@ -303,20 +303,14 @@ impl<'a, C: Channel> Transfer<'a, C> {
         ch.cr().write(|w| {
             w.set_psize(data_size.into());
             w.set_msize(data_size.into());
-            if incr_mem {
+            w.set_minc(incr_mem);
-                w.set_minc(vals::Inc::ENABLED);
-            } else {
-                w.set_minc(vals::Inc::DISABLED);
-            }
             w.set_dir(dir.into());
             w.set_teie(true);
             w.set_tcie(options.complete_transfer_ir);
             w.set_htie(options.half_transfer_ir);
+            w.set_circ(options.circular);
             if options.circular {
-                w.set_circ(vals::Circ::ENABLED);
                 debug!("Setting circular mode");
-            } else {
-                w.set_circ(vals::Circ::DISABLED);
             }
             w.set_pl(vals::Pl::VERYHIGH);
             w.set_en(true);
@@ -352,7 +346,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
     pub fn is_running(&mut self) -> bool {
         let ch = self.channel.regs().ch(self.channel.num());
         let en = ch.cr().read().en();
-        let circular = ch.cr().read().circ() == vals::Circ::ENABLED;
+        let circular = ch.cr().read().circ();
         let tcif = STATE.complete_count[self.channel.index()].load(Ordering::Acquire) != 0;
         en && (circular || !tcif)
     }
@@ -467,12 +461,12 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
         let mut w = regs::Cr(0);
         w.set_psize(data_size.into());
         w.set_msize(data_size.into());
-        w.set_minc(vals::Inc::ENABLED);
+        w.set_minc(true);
         w.set_dir(dir.into());
         w.set_teie(true);
         w.set_htie(true);
         w.set_tcie(true);
-        w.set_circ(vals::Circ::ENABLED);
+        w.set_circ(true);
         w.set_pl(vals::Pl::VERYHIGH);
         w.set_en(true);
 
@@ -625,12 +619,12 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
         let mut w = regs::Cr(0);
         w.set_psize(data_size.into());
         w.set_msize(data_size.into());
-        w.set_minc(vals::Inc::ENABLED);
+        w.set_minc(true);
         w.set_dir(dir.into());
         w.set_teie(true);
         w.set_htie(true);
         w.set_tcie(true);
-        w.set_circ(vals::Circ::ENABLED);
+        w.set_circ(true);
         w.set_pl(vals::Pl::VERYHIGH);
         w.set_en(true);
 

embassy-stm32/src/dma/dma.rs

@@ -382,18 +382,13 @@ impl<'a, C: Channel> Transfer<'a, C> {
             w.set_msize(data_size.into());
             w.set_psize(data_size.into());
             w.set_pl(vals::Pl::VERYHIGH);
-            w.set_minc(match incr_mem {
+            w.set_minc(incr_mem);
-                true => vals::Inc::INCREMENTED,
+            w.set_pinc(false);
-                false => vals::Inc::FIXED,
-            });
-            w.set_pinc(vals::Inc::FIXED);
             w.set_teie(true);
             w.set_tcie(options.complete_transfer_ir);
+            w.set_circ(options.circular);
             if options.circular {
-                w.set_circ(vals::Circ::ENABLED);
                 debug!("Setting circular mode");
-            } else {
-                w.set_circ(vals::Circ::DISABLED);
             }
             #[cfg(dma_v1)]
             w.set_trbuff(true);
@@ -545,8 +540,8 @@ impl<'a, C: Channel, W: Word> DoubleBuffered<'a, C, W> {
             w.set_msize(data_size.into());
             w.set_psize(data_size.into());
             w.set_pl(vals::Pl::VERYHIGH);
-            w.set_minc(vals::Inc::INCREMENTED);
+            w.set_minc(true);
-            w.set_pinc(vals::Inc::FIXED);
+            w.set_pinc(false);
             w.set_teie(true);
             w.set_tcie(true);
             #[cfg(dma_v1)]
@@ -703,12 +698,12 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
         w.set_msize(data_size.into());
         w.set_psize(data_size.into());
         w.set_pl(vals::Pl::VERYHIGH);
-        w.set_minc(vals::Inc::INCREMENTED);
+        w.set_minc(true);
-        w.set_pinc(vals::Inc::FIXED);
+        w.set_pinc(false);
         w.set_teie(true);
         w.set_htie(options.half_transfer_ir);
         w.set_tcie(true);
-        w.set_circ(vals::Circ::ENABLED);
+        w.set_circ(true);
         #[cfg(dma_v1)]
         w.set_trbuff(true);
         #[cfg(dma_v2)]
@@ -878,12 +873,12 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
         w.set_msize(data_size.into());
         w.set_psize(data_size.into());
         w.set_pl(vals::Pl::VERYHIGH);
-        w.set_minc(vals::Inc::INCREMENTED);
+        w.set_minc(true);
-        w.set_pinc(vals::Inc::FIXED);
+        w.set_pinc(false);
         w.set_teie(true);
         w.set_htie(options.half_transfer_ir);
         w.set_tcie(true);
-        w.set_circ(vals::Circ::ENABLED);
+        w.set_circ(true);
         #[cfg(dma_v1)]
         w.set_trbuff(true);
         #[cfg(dma_v2)]

embassy-stm32/src/dma/gpdma.rs

@@ -16,6 +16,7 @@ use crate::interrupt::Priority;
 use crate::pac;
 use crate::pac::gpdma::vals;
 
+/// GPDMA transfer options.
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[non_exhaustive]
@@ -113,10 +114,13 @@ pub(crate) unsafe fn on_irq_inner(dma: pac::gpdma::Gpdma, channel_num: usize, in
     }
 }
 
+/// DMA request type alias. (also known as DMA channel number in some chips)
 pub type Request = u8;
 
+/// DMA channel.
 #[cfg(dmamux)]
 pub trait Channel: sealed::Channel + Peripheral<P = Self> + 'static + super::dmamux::MuxChannel {}
+/// DMA channel.
 #[cfg(not(dmamux))]
 pub trait Channel: sealed::Channel + Peripheral<P = Self> + 'static {}
 
@@ -131,12 +135,14 @@ pub(crate) mod sealed {
     }
 }
 
+/// DMA transfer.
 #[must_use = "futures do nothing unless you `.await` or poll them"]
 pub struct Transfer<'a, C: Channel> {
     channel: PeripheralRef<'a, C>,
 }
 
 impl<'a, C: Channel> Transfer<'a, C> {
+    /// Create a new read DMA transfer (peripheral to memory).
     pub unsafe fn new_read<W: Word>(
         channel: impl Peripheral<P = C> + 'a,
         request: Request,
@@ -147,6 +153,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
         Self::new_read_raw(channel, request, peri_addr, buf, options)
     }
 
+    /// Create a new read DMA transfer (peripheral to memory), using raw pointers.
     pub unsafe fn new_read_raw<W: Word>(
         channel: impl Peripheral<P = C> + 'a,
         request: Request,
@@ -172,6 +179,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
         )
     }
 
+    /// Create a new write DMA transfer (memory to peripheral).
     pub unsafe fn new_write<W: Word>(
         channel: impl Peripheral<P = C> + 'a,
         request: Request,
@@ -182,6 +190,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
         Self::new_write_raw(channel, request, buf, peri_addr, options)
     }
 
+    /// Create a new write DMA transfer (memory to peripheral), using raw pointers.
     pub unsafe fn new_write_raw<W: Word>(
         channel: impl Peripheral<P = C> + 'a,
         request: Request,
@@ -207,6 +216,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
         )
     }
 
+    /// Create a new write DMA transfer (memory to peripheral), writing the same value repeatedly.
     pub unsafe fn new_write_repeated<W: Word>(
         channel: impl Peripheral<P = C> + 'a,
         request: Request,
@@ -297,6 +307,9 @@ impl<'a, C: Channel> Transfer<'a, C> {
         this
     }
 
+    /// Request the transfer to stop.
+    ///
+    /// This doesn't immediately stop the transfer, you have to wait until [`is_running`](Self::is_running) returns false.
     pub fn request_stop(&mut self) {
         let ch = self.channel.regs().ch(self.channel.num());
         ch.cr().modify(|w| {
@@ -304,6 +317,10 @@ impl<'a, C: Channel> Transfer<'a, C> {
         })
     }
 
+    /// Return whether this transfer is still running.
+    ///
+    /// If this returns `false`, it can be because either the transfer finished, or
+    /// it was requested to stop early with [`request_stop`](Self::request_stop).
     pub fn is_running(&mut self) -> bool {
         let ch = self.channel.regs().ch(self.channel.num());
         let sr = ch.sr().read();
@@ -317,6 +334,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
         ch.br1().read().bndt()
     }
 
+    /// Blocking wait until the transfer finishes.
     pub fn blocking_wait(mut self) {
         while self.is_running() {}
 

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

embassy-stm32/src/hrtim/mod.rs

@@ -1,3 +1,5 @@
+//! High Resolution Timer (HRTIM)
+
 mod traits;
 
 use core::marker::PhantomData;
@@ -13,38 +15,42 @@ use crate::rcc::get_freqs;
 use crate::time::Hertz;
 use crate::Peripheral;
 
-pub enum Source {
+/// HRTIM burst controller instance.
-    Master,
-    ChA,
-    ChB,
-    ChC,
-    ChD,
-    ChE,
-    #[cfg(hrtim_v2)]
-    ChF,
-}
-
 pub struct BurstController<T: Instance> {
     phantom: PhantomData<T>,
 }
+
+/// HRTIM master instance.
 pub struct Master<T: Instance> {
     phantom: PhantomData<T>,
 }
+
+/// HRTIM channel A instance.
 pub struct ChA<T: Instance> {
     phantom: PhantomData<T>,
 }
+
+/// HRTIM channel B instance.
 pub struct ChB<T: Instance> {
     phantom: PhantomData<T>,
 }
+
+/// HRTIM channel C instance.
 pub struct ChC<T: Instance> {
     phantom: PhantomData<T>,
 }
+
+/// HRTIM channel D instance.
 pub struct ChD<T: Instance> {
     phantom: PhantomData<T>,
 }
+
+/// HRTIM channel E instance.
 pub struct ChE<T: Instance> {
     phantom: PhantomData<T>,
 }
+
+/// HRTIM channel F instance.
 #[cfg(hrtim_v2)]
 pub struct ChF<T: Instance> {
     phantom: PhantomData<T>,
@@ -58,22 +64,26 @@ mod sealed {
     }
 }
 
+/// Advanced channel instance trait.
 pub trait AdvancedChannel<T: Instance>: sealed::AdvancedChannel<T> {}
 
-pub struct PwmPin<'d, Perip, Channel> {
+/// HRTIM PWM pin.
+pub struct PwmPin<'d, T, C> {
     _pin: PeripheralRef<'d, AnyPin>,
-    phantom: PhantomData<(Perip, Channel)>,
+    phantom: PhantomData<(T, C)>,
 }
 
-pub struct ComplementaryPwmPin<'d, Perip, Channel> {
+/// HRTIM complementary PWM pin.
+pub struct ComplementaryPwmPin<'d, T, C> {
     _pin: PeripheralRef<'d, AnyPin>,
-    phantom: PhantomData<(Perip, Channel)>,
+    phantom: PhantomData<(T, C)>,
 }
 
 macro_rules! advanced_channel_impl {
     ($new_chx:ident, $channel:tt, $ch_num:expr, $pin_trait:ident, $complementary_pin_trait:ident) => {
-        impl<'d, Perip: Instance> PwmPin<'d, Perip, $channel<Perip>> {
+        impl<'d, T: Instance> PwmPin<'d, T, $channel<T>> {
-            pub fn $new_chx(pin: impl Peripheral<P = impl $pin_trait<Perip>> + 'd) -> Self {
+            #[doc = concat!("Create a new ", stringify!($channel), " PWM pin instance.")]
+            pub fn $new_chx(pin: impl Peripheral<P = impl $pin_trait<T>> + 'd) -> Self {
                 into_ref!(pin);
                 critical_section::with(|_| {
                     pin.set_low();
@@ -88,8 +98,9 @@ macro_rules! advanced_channel_impl {
             }
         }
 
-        impl<'d, Perip: Instance> ComplementaryPwmPin<'d, Perip, $channel<Perip>> {
+        impl<'d, T: Instance> ComplementaryPwmPin<'d, T, $channel<T>> {
-            pub fn $new_chx(pin: impl Peripheral<P = impl $complementary_pin_trait<Perip>> + 'd) -> Self {
+            #[doc = concat!("Create a new ", stringify!($channel), " complementary PWM pin instance.")]
+            pub fn $new_chx(pin: impl Peripheral<P = impl $complementary_pin_trait<T>> + 'd) -> Self {
                 into_ref!(pin);
                 critical_section::with(|_| {
                     pin.set_low();
@@ -124,18 +135,29 @@ advanced_channel_impl!(new_chf, ChF, 5, ChannelFPin, ChannelFComplementaryPin);
 /// Struct used to divide a high resolution timer into multiple channels
 pub struct AdvancedPwm<'d, T: Instance> {
     _inner: PeripheralRef<'d, T>,
+    /// Master instance.
     pub master: Master<T>,
+    /// Burst controller.
     pub burst_controller: BurstController<T>,
+    /// Channel A.
     pub ch_a: ChA<T>,
+    /// Channel B.
     pub ch_b: ChB<T>,
+    /// Channel C.
     pub ch_c: ChC<T>,
+    /// Channel D.
     pub ch_d: ChD<T>,
+    /// Channel E.
     pub ch_e: ChE<T>,
+    /// Channel F.
     #[cfg(hrtim_v2)]
     pub ch_f: ChF<T>,
 }
 
 impl<'d, T: Instance> AdvancedPwm<'d, T> {
+    /// Create a new HRTIM driver.
+    ///
+    /// This splits the HRTIM into its constituent parts, which you can then use individually.
     pub fn new(
         tim: impl Peripheral<P = T> + 'd,
         _cha: Option<PwmPin<'d, T, ChA<T>>>,
@@ -198,13 +220,7 @@ impl<'d, T: Instance> AdvancedPwm<'d, T> {
     }
 }
 
-impl<T: Instance> BurstController<T> {
+/// Fixed-frequency bridge converter driver.
-    pub fn set_source(&mut self, _source: Source) {
-        todo!("burst mode control registers not implemented")
-    }
-}
-
-/// Represents a fixed-frequency bridge converter
 ///
 /// Our implementation of the bridge converter uses a single channel and three compare registers,
 /// allowing implementation of a synchronous buck or boost converter in continuous or discontinuous
@@ -223,6 +239,7 @@ pub struct BridgeConverter<T: Instance, C: AdvancedChannel<T>> {
 }
 
 impl<T: Instance, C: AdvancedChannel<T>> BridgeConverter<T, C> {
+    /// Create a new HRTIM bridge converter driver.
     pub fn new(_channel: C, frequency: Hertz) -> Self {
         use crate::pac::hrtim::vals::{Activeeffect, Inactiveeffect};
 
@@ -279,14 +296,17 @@ impl<T: Instance, C: AdvancedChannel<T>> BridgeConverter<T, C> {
         }
     }
 
+    /// Start HRTIM.
     pub fn start(&mut self) {
         T::regs().mcr().modify(|w| w.set_tcen(C::raw(), true));
     }
 
+    /// Stop HRTIM.
     pub fn stop(&mut self) {
         T::regs().mcr().modify(|w| w.set_tcen(C::raw(), false));
     }
 
+    /// Enable burst mode.
     pub fn enable_burst_mode(&mut self) {
         T::regs().tim(C::raw()).outr().modify(|w| {
             // Enable Burst Mode
@@ -299,6 +319,7 @@ impl<T: Instance, C: AdvancedChannel<T>> BridgeConverter<T, C> {
         })
     }
 
+    /// Disable burst mode.
     pub fn disable_burst_mode(&mut self) {
         T::regs().tim(C::raw()).outr().modify(|w| {
             // Disable Burst Mode
@@ -355,7 +376,7 @@ impl<T: Instance, C: AdvancedChannel<T>> BridgeConverter<T, C> {
     }
 }
 
-/// Represents a variable-frequency resonant converter
+/// Variable-frequency resonant converter driver.
 ///
 /// This implementation of a resonsant converter is appropriate for a half or full bridge,
 /// but does not include secondary rectification, which is appropriate for applications
@@ -368,6 +389,7 @@ pub struct ResonantConverter<T: Instance, C: AdvancedChannel<T>> {
 }
 
 impl<T: Instance, C: AdvancedChannel<T>> ResonantConverter<T, C> {
+    /// Create a new variable-frequency resonant converter driver.
     pub fn new(_channel: C, min_frequency: Hertz, max_frequency: Hertz) -> Self {
         T::set_channel_frequency(C::raw(), min_frequency);
 
@@ -406,6 +428,7 @@ impl<T: Instance, C: AdvancedChannel<T>> ResonantConverter<T, C> {
         T::set_channel_dead_time(C::raw(), value);
     }
 
+    /// Set the timer period.
     pub fn set_period(&mut self, period: u16) {
         assert!(period < self.max_period);
         assert!(period > self.min_period);

embassy-stm32/src/hrtim/traits.rs

@@ -125,7 +125,6 @@ pub(crate) mod sealed {
         }
 
         /// Set the dead time as a proportion of max_duty
-
         fn set_channel_dead_time(channel: usize, dead_time: u16) {
             let regs = Self::regs();
 
@@ -148,13 +147,10 @@ pub(crate) mod sealed {
                 w.set_dtr(dt_val as u16);
             });
         }
-
-        //        fn enable_outputs(enable: bool);
-        //
-        //        fn enable_channel(&mut self, channel: usize, enable: bool);
     }
 }
 
+/// HRTIM instance trait.
 pub trait Instance: sealed::Instance + 'static {}
 
 foreach_interrupt! {

embassy-stm32/src/i2c/mod.rs

@@ -1,3 +1,4 @@
+//! Inter-Integrated-Circuit (I2C)
 #![macro_use]
 
 #[cfg_attr(i2c_v1, path = "v1.rs")]
@@ -147,38 +148,31 @@ struct Timeout {
 
 #[allow(dead_code)]
 impl Timeout {
-    #[cfg(not(feature = "time"))]
     #[inline]
     fn check(self) -> Result<(), Error> {
+        #[cfg(feature = "time")]
+        if Instant::now() > self.deadline {
+            return Err(Error::Timeout);
+        }
+
         Ok(())
     }
 
-    #[cfg(feature = "time")]
     #[inline]
-    fn check(self) -> Result<(), Error> {
+    fn with<R>(self, fut: impl Future<Output = Result<R, Error>>) -> impl Future<Output = Result<R, Error>> {
-        if Instant::now() > self.deadline {
+        #[cfg(feature = "time")]
-            Err(Error::Timeout)
+        {
-        } else {
+            use futures::FutureExt;
-            Ok(())
+
+            embassy_futures::select::select(embassy_time::Timer::at(self.deadline), fut).map(|r| match r {
+                embassy_futures::select::Either::First(_) => Err(Error::Timeout),
+                embassy_futures::select::Either::Second(r) => r,
+            })
         }
-    }
 
-    #[cfg(not(feature = "time"))]
+        #[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 {

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

embassy-stm32/src/ipcc.rs

@@ -1,3 +1,5 @@
+//! Inter-Process Communication Controller (IPCC)
+
 use core::future::poll_fn;
 use core::sync::atomic::{compiler_fence, Ordering};
 use core::task::Poll;
@@ -41,6 +43,7 @@ impl interrupt::typelevel::Handler<interrupt::typelevel::IPCC_C1_RX> for Receive
     }
 }
 
+/// TX interrupt handler.
 pub struct TransmitInterruptHandler {}
 
 impl interrupt::typelevel::Handler<interrupt::typelevel::IPCC_C1_TX> for TransmitInterruptHandler {
@@ -72,6 +75,7 @@ impl interrupt::typelevel::Handler<interrupt::typelevel::IPCC_C1_TX> for Transmi
     }
 }
 
+/// IPCC config.
 #[non_exhaustive]
 #[derive(Clone, Copy, Default)]
 pub struct Config {
@@ -79,6 +83,8 @@ pub struct Config {
     // reserved for future use
 }
 
+/// Channel.
+#[allow(missing_docs)]
 #[derive(Debug, Clone, Copy)]
 #[repr(C)]
 pub enum IpccChannel {
@@ -90,9 +96,11 @@ pub enum IpccChannel {
     Channel6 = 5,
 }
 
+/// IPCC driver.
 pub struct Ipcc;
 
 impl Ipcc {
+    /// Enable IPCC.
     pub fn enable(_config: Config) {
         IPCC::enable_and_reset();
         IPCC::set_cpu2(true);

embassy-stm32/src/lib.rs

@@ -1,5 +1,6 @@
 #![cfg_attr(not(test), no_std)]
 #![allow(async_fn_in_trait)]
+#![warn(missing_docs)]
 
 //! ## Feature flags
 #![doc = document_features::document_features!(feature_label = r#"<span class="stab portability"><code>{feature}</code></span>"#)]
@@ -79,6 +80,7 @@ pub(crate) mod _generated {
     #![allow(dead_code)]
     #![allow(unused_imports)]
     #![allow(non_snake_case)]
+    #![allow(missing_docs)]
 
     include!(concat!(env!("OUT_DIR"), "/_generated.rs"));
 }
@@ -149,15 +151,33 @@ use crate::interrupt::Priority;
 pub use crate::pac::NVIC_PRIO_BITS;
 use crate::rcc::sealed::RccPeripheral;
 
+/// `embassy-stm32` global configuration.
 #[non_exhaustive]
 pub struct Config {
+    /// RCC config.
     pub rcc: rcc::Config,
+
+    /// Enable debug during sleep.
+    ///
+    /// May incrase power consumption. Defaults to true.
     #[cfg(dbgmcu)]
     pub enable_debug_during_sleep: bool,
+
+    /// BDMA interrupt priority.
+    ///
+    /// Defaults to P0 (highest).
     #[cfg(bdma)]
     pub bdma_interrupt_priority: Priority,
+
+    /// DMA interrupt priority.
+    ///
+    /// Defaults to P0 (highest).
     #[cfg(dma)]
     pub dma_interrupt_priority: Priority,
+
+    /// GPDMA interrupt priority.
+    ///
+    /// Defaults to P0 (highest).
     #[cfg(gpdma)]
     pub gpdma_interrupt_priority: Priority,
 }
@@ -178,7 +198,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/low_power.rs

@@ -1,50 +1,53 @@
-/// The STM32 line of microcontrollers support various deep-sleep modes which exploit clock-gating
+//! Low-power support.
-/// to reduce power consumption. `embassy-stm32` provides a low-power executor, [`Executor`] which
+//!
-/// can use knowledge of which peripherals are currently blocked upon to transparently and safely
+//! The STM32 line of microcontrollers support various deep-sleep modes which exploit clock-gating
-/// enter such low-power modes (currently, only `STOP2`) when idle.
+//! to reduce power consumption. `embassy-stm32` provides a low-power executor, [`Executor`] which
-///
+//! can use knowledge of which peripherals are currently blocked upon to transparently and safely
-/// The executor determines which peripherals are active by their RCC state; consequently,
+//! enter such low-power modes (currently, only `STOP2`) when idle.
-/// low-power states can only be entered if all peripherals have been `drop`'d. There are a few
+//!
-/// exceptions to this rule:
+//! The executor determines which peripherals are active by their RCC state; consequently,
-///
+//! low-power states can only be entered if all peripherals have been `drop`'d. There are a few
-///  * `GPIO`
+//! exceptions to this rule:
-///  * `RCC`
+//!
-///
+//!  * `GPIO`
-/// Since entering and leaving low-power modes typically incurs a significant latency, the
+//!  * `RCC`
-/// low-power executor will only attempt to enter when the next timer event is at least
+//!
-/// [`time_driver::MIN_STOP_PAUSE`] in the future.
+//! Since entering and leaving low-power modes typically incurs a significant latency, the
-///
+//! low-power executor will only attempt to enter when the next timer event is at least
-/// Currently there is no macro analogous to `embassy_executor::main` for this executor;
+//! [`time_driver::MIN_STOP_PAUSE`] in the future.
-/// consequently one must define their entrypoint manually. Moveover, you must relinquish control
+//!
-/// of the `RTC` peripheral to the executor. This will typically look like
+//! Currently there is no macro analogous to `embassy_executor::main` for this executor;
-///
+//! consequently one must define their entrypoint manually. Moveover, you must relinquish control
-/// ```rust,no_run
+//! of the `RTC` peripheral to the executor. This will typically look like
-/// use embassy_executor::Spawner;
+//!
-/// use embassy_stm32::low_power::Executor;
+//! ```rust,no_run
-/// use embassy_stm32::rtc::{Rtc, RtcConfig};
+//! use embassy_executor::Spawner;
-/// use static_cell::make_static;
+//! use embassy_stm32::low_power::Executor;
-///
+//! use embassy_stm32::rtc::{Rtc, RtcConfig};
-/// #[cortex_m_rt::entry]
+//! use static_cell::make_static;
-/// fn main() -> ! {
+//!
-///     Executor::take().run(|spawner| {
+//! #[cortex_m_rt::entry]
-///         unwrap!(spawner.spawn(async_main(spawner)));
+//! fn main() -> ! {
-///     });
+//!     Executor::take().run(|spawner| {
-/// }
+//!         unwrap!(spawner.spawn(async_main(spawner)));
-///
+//!     });
-/// #[embassy_executor::task]
+//! }
-/// async fn async_main(spawner: Spawner) {
+//!
-///     // initialize the platform...
+//! #[embassy_executor::task]
-///     let mut config = embassy_stm32::Config::default();
+//! async fn async_main(spawner: Spawner) {
-///     let p = embassy_stm32::init(config);
+//!     // initialize the platform...
-///
+//!     let mut config = embassy_stm32::Config::default();
-///     // give the RTC to the executor...
+//!     let p = embassy_stm32::init(config);
-///     let mut rtc = Rtc::new(p.RTC, RtcConfig::default());
+//!
-///     let rtc = make_static!(rtc);
+//!     // give the RTC to the executor...
-///     embassy_stm32::low_power::stop_with_rtc(rtc);
+//!     let mut rtc = Rtc::new(p.RTC, RtcConfig::default());
-///
+//!     let rtc = make_static!(rtc);
-///     // your application here...
+//!     embassy_stm32::low_power::stop_with_rtc(rtc);
-/// }
+//!
-/// ```
+//!     // your application here...
+//! }
+//! ```
+
 use core::arch::asm;
 use core::marker::PhantomData;
 use core::sync::atomic::{compiler_fence, Ordering};
@@ -64,6 +67,7 @@ static mut EXECUTOR: Option<Executor> = None;
 foreach_interrupt! {
     (RTC, rtc, $block:ident, WKUP, $irq:ident) => {
         #[interrupt]
+        #[allow(non_snake_case)]
         unsafe fn $irq() {
             EXECUTOR.as_mut().unwrap().on_wakeup_irq();
         }
@@ -75,10 +79,15 @@ pub(crate) unsafe fn on_wakeup_irq() {
     EXECUTOR.as_mut().unwrap().on_wakeup_irq();
 }
 
+/// Configure STOP mode with RTC.
 pub fn stop_with_rtc(rtc: &'static Rtc) {
     unsafe { EXECUTOR.as_mut().unwrap() }.stop_with_rtc(rtc)
 }
 
+/// Get whether the core is ready to enter the given stop mode.
+///
+/// This will return false if some peripheral driver is in use that
+/// prevents entering the given stop mode.
 pub fn stop_ready(stop_mode: StopMode) -> bool {
     match unsafe { EXECUTOR.as_mut().unwrap() }.stop_mode() {
         Some(StopMode::Stop2) => true,
@@ -87,10 +96,13 @@ pub fn stop_ready(stop_mode: StopMode) -> bool {
     }
 }
 
+/// Available stop modes.
 #[non_exhaustive]
 #[derive(PartialEq)]
 pub enum StopMode {
+    /// STOP 1
     Stop1,
+    /// STOP 2
     Stop2,
 }
 

embassy-stm32/src/opamp.rs

@@ -1,9 +1,12 @@
+//! Operational Amplifier (OPAMP)
 #![macro_use]
 
 use embassy_hal_internal::{into_ref, PeripheralRef};
 
 use crate::Peripheral;
 
+/// Gain
+#[allow(missing_docs)]
 #[derive(Clone, Copy)]
 pub enum OpAmpGain {
     Mul1,
@@ -13,6 +16,8 @@ pub enum OpAmpGain {
     Mul16,
 }
 
+/// Speed
+#[allow(missing_docs)]
 #[derive(Clone, Copy)]
 pub enum OpAmpSpeed {
     Normal,
@@ -180,6 +185,7 @@ impl<'d, T: Instance> Drop for OpAmpInternalOutput<'d, T> {
     }
 }
 
+/// Opamp instance trait.
 pub trait Instance: sealed::Instance + 'static {}
 
 pub(crate) mod sealed {
@@ -198,8 +204,11 @@ pub(crate) mod sealed {
     pub trait OutputPin<T: Instance> {}
 }
 
+/// Non-inverting pin trait.
 pub trait NonInvertingPin<T: Instance>: sealed::NonInvertingPin<T> {}
+/// Inverting pin trait.
 pub trait InvertingPin<T: Instance>: sealed::InvertingPin<T> {}
+/// Output pin trait.
 pub trait OutputPin<T: Instance>: sealed::OutputPin<T> {}
 
 macro_rules! impl_opamp_external_output {

embassy-stm32/src/qspi/enums.rs

@@ -1,3 +1,5 @@
+//! Enums used in QSPI configuration.
+
 #[allow(dead_code)]
 #[derive(Copy, Clone)]
 pub(crate) enum QspiMode {

embassy-stm32/src/qspi/mod.rs

@@ -1,3 +1,5 @@
+//! Quad Serial Peripheral Interface (QSPI)
+
 #![macro_use]
 
 pub mod enums;
@@ -12,6 +14,7 @@ use crate::pac::quadspi::Quadspi as Regs;
 use crate::rcc::RccPeripheral;
 use crate::{peripherals, Peripheral};
 
+/// QSPI transfer configuration.
 pub struct TransferConfig {
     /// Instraction width (IMODE)
     pub iwidth: QspiWidth,
@@ -43,6 +46,7 @@ impl Default for TransferConfig {
     }
 }
 
+/// QSPI driver configuration.
 pub struct Config {
     /// Flash memory size representend as 2^[0-32], as reasonable minimum 1KiB(9) was chosen.
     /// If you need other value the whose predefined use `Other` variant.
@@ -69,6 +73,7 @@ impl Default for Config {
     }
 }
 
+/// QSPI driver.
 #[allow(dead_code)]
 pub struct Qspi<'d, T: Instance, Dma> {
     _peri: PeripheralRef<'d, T>,
@@ -83,6 +88,7 @@ pub struct Qspi<'d, T: Instance, Dma> {
 }
 
 impl<'d, T: Instance, Dma> Qspi<'d, T, Dma> {
+    /// Create a new QSPI driver for bank 1.
     pub fn new_bk1(
         peri: impl Peripheral<P = T> + 'd,
         d0: impl Peripheral<P = impl BK1D0Pin<T>> + 'd,
@@ -123,6 +129,7 @@ impl<'d, T: Instance, Dma> Qspi<'d, T, Dma> {
         )
     }
 
+    /// Create a new QSPI driver for bank 2.
     pub fn new_bk2(
         peri: impl Peripheral<P = T> + 'd,
         d0: impl Peripheral<P = impl BK2D0Pin<T>> + 'd,
@@ -221,6 +228,7 @@ impl<'d, T: Instance, Dma> Qspi<'d, T, Dma> {
         }
     }
 
+    /// Do a QSPI command.
     pub fn command(&mut self, transaction: TransferConfig) {
         #[cfg(not(stm32h7))]
         T::REGS.cr().modify(|v| v.set_dmaen(false));
@@ -230,6 +238,7 @@ impl<'d, T: Instance, Dma> Qspi<'d, T, Dma> {
         T::REGS.fcr().modify(|v| v.set_ctcf(true));
     }
 
+    /// Blocking read data.
     pub fn blocking_read(&mut self, buf: &mut [u8], transaction: TransferConfig) {
         #[cfg(not(stm32h7))]
         T::REGS.cr().modify(|v| v.set_dmaen(false));
@@ -254,6 +263,7 @@ impl<'d, T: Instance, Dma> Qspi<'d, T, Dma> {
         T::REGS.fcr().modify(|v| v.set_ctcf(true));
     }
 
+    /// Blocking write data.
     pub fn blocking_write(&mut self, buf: &[u8], transaction: TransferConfig) {
         // STM32H7 does not have dmaen
         #[cfg(not(stm32h7))]
@@ -276,6 +286,7 @@ impl<'d, T: Instance, Dma> Qspi<'d, T, Dma> {
         T::REGS.fcr().modify(|v| v.set_ctcf(true));
     }
 
+    /// Blocking read data, using DMA.
     pub fn blocking_read_dma(&mut self, buf: &mut [u8], transaction: TransferConfig)
     where
         Dma: QuadDma<T>,
@@ -308,6 +319,7 @@ impl<'d, T: Instance, Dma> Qspi<'d, T, Dma> {
         transfer.blocking_wait();
     }
 
+    /// Blocking write data, using DMA.
     pub fn blocking_write_dma(&mut self, buf: &[u8], transaction: TransferConfig)
     where
         Dma: QuadDma<T>,
@@ -377,6 +389,7 @@ pub(crate) mod sealed {
     }
 }
 
+/// QSPI instance trait.
 pub trait Instance: Peripheral<P = Self> + sealed::Instance + RccPeripheral {}
 
 pin_trait!(SckPin, Instance);

embassy-stm32/src/rng.rs

@@ -1,3 +1,4 @@
+//! Random Number Generator (RNG)
 #![macro_use]
 
 use core::future::poll_fn;
@@ -79,6 +80,7 @@ impl<'d, T: Instance> Rng<'d, T> {
         let _ = self.next_u32();
     }
 
+    /// Reset the RNG.
     #[cfg(not(rng_v1))]
     pub fn reset(&mut self) {
         T::regs().cr().write(|reg| {

embassy-stm32/src/rtc/mod.rs

@@ -1,4 +1,4 @@
-//! RTC peripheral abstraction
+//! Real Time Clock (RTC)
 mod datetime;
 
 #[cfg(feature = "low-power")]
@@ -130,7 +130,7 @@ impl RtcTimeProvider {
             let weekday = day_of_week_from_u8(dr.wdu()).map_err(RtcError::InvalidDateTime)?;
             let day = bcd2_to_byte((dr.dt(), dr.du()));
             let month = bcd2_to_byte((dr.mt() as u8, dr.mu()));
-            let year = bcd2_to_byte((dr.yt(), dr.yu())) as u16 + 1970_u16;
+            let year = bcd2_to_byte((dr.yt(), dr.yu())) as u16 + 2000_u16;
 
             DateTime::from(year, month, day, weekday, hour, minute, second).map_err(RtcError::InvalidDateTime)
         })
@@ -163,7 +163,7 @@ impl RtcTimeProvider {
     }
 }
 
-/// RTC Abstraction
+/// RTC driver.
 pub struct Rtc {
     #[cfg(feature = "low-power")]
     stop_time: Mutex<CriticalSectionRawMutex, Cell<Option<RtcInstant>>>,
@@ -261,7 +261,7 @@ impl Rtc {
             let (dt, du) = byte_to_bcd2(t.day() as u8);
             let (mt, mu) = byte_to_bcd2(t.month() as u8);
             let yr = t.year() as u16;
-            let yr_offset = (yr - 1970_u16) as u8;
+            let yr_offset = (yr - 2000_u16) as u8;
             let (yt, yu) = byte_to_bcd2(yr_offset);
 
             use crate::pac::rtc::vals::Ampm;

embassy-stm32/src/sai/mod.rs

@@ -1,8 +1,11 @@
+//! Serial Audio Interface (SAI)
 #![macro_use]
 
-use embassy_embedded_hal::SetConfig;
+use core::marker::PhantomData;
+
 use embassy_hal_internal::{into_ref, PeripheralRef};
 
+use self::sealed::WhichSubBlock;
 pub use crate::dma::word;
 use crate::dma::{ringbuffer, Channel, ReadableRingBuffer, Request, TransferOptions, WritableRingBuffer};
 use crate::gpio::sealed::{AFType, Pin as _};
@@ -11,48 +14,32 @@ use crate::pac::sai::{vals, Sai as Regs};
 use crate::rcc::RccPeripheral;
 use crate::{peripherals, Peripheral};
 
+/// SAI error
 #[derive(Debug, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Error {
+    /// `write` called on a SAI in receive mode.
     NotATransmitter,
+    /// `read` called on a SAI in transmit mode.
     NotAReceiver,
-    OverrunError,
+    /// Overrun
+    Overrun,
 }
 
 impl From<ringbuffer::OverrunError> for Error {
     fn from(_: ringbuffer::OverrunError) -> Self {
-        Self::OverrunError
+        Self::Overrun
     }
 }
 
+/// Master/slave mode.
 #[derive(Copy, Clone)]
-pub enum SyncBlock {
+#[allow(missing_docs)]
-    None,
-    Sai1BlockA,
-    Sai1BlockB,
-    Sai2BlockA,
-    Sai2BlockB,
-}
-
-#[derive(Copy, Clone)]
-pub enum SyncIn {
-    None,
-    ChannelZero,
-    ChannelOne,
-}
-
-#[derive(Copy, Clone)]
 pub enum Mode {
     Master,
     Slave,
 }
 
-#[derive(Copy, Clone)]
-pub enum TxRx {
-    Transmitter,
-    Receiver,
-}
-
 impl Mode {
     #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
     const fn mode(&self, tx_rx: TxRx) -> vals::Mode {
@@ -69,7 +56,17 @@ impl Mode {
     }
 }
 
+/// Direction: transmit or receive
 #[derive(Copy, Clone)]
+#[allow(missing_docs)]
+pub enum TxRx {
+    Transmitter,
+    Receiver,
+}
+
+/// Data slot size.
+#[derive(Copy, Clone)]
+#[allow(missing_docs)]
 pub enum SlotSize {
     DataSize,
     /// 16 bit data length on 16 bit wide channel
@@ -80,7 +77,7 @@ pub enum SlotSize {
 
 impl SlotSize {
     #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn slotsz(&self) -> vals::Slotsz {
+    const fn slotsz(&self) -> vals::Slotsz {
         match self {
             SlotSize::DataSize => vals::Slotsz::DATASIZE,
             SlotSize::Channel16 => vals::Slotsz::BIT16,
@@ -89,7 +86,9 @@ impl SlotSize {
     }
 }
 
+/// Data size.
 #[derive(Copy, Clone)]
+#[allow(missing_docs)]
 pub enum DataSize {
     Data8,
     Data10,
@@ -101,7 +100,7 @@ pub enum DataSize {
 
 impl DataSize {
     #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn ds(&self) -> vals::Ds {
+    const fn ds(&self) -> vals::Ds {
         match self {
             DataSize::Data8 => vals::Ds::BIT8,
             DataSize::Data10 => vals::Ds::BIT10,
@@ -113,7 +112,9 @@ impl DataSize {
     }
 }
 
+/// FIFO threshold level.
 #[derive(Copy, Clone)]
+#[allow(missing_docs)]
 pub enum FifoThreshold {
     Empty,
     Quarter,
@@ -124,7 +125,7 @@ pub enum FifoThreshold {
 
 impl FifoThreshold {
     #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn fth(&self) -> vals::Fth {
+    const fn fth(&self) -> vals::Fth {
         match self {
             FifoThreshold::Empty => vals::Fth::EMPTY,
             FifoThreshold::Quarter => vals::Fth::QUARTER1,
@@ -135,38 +136,9 @@ impl FifoThreshold {
     }
 }
 
+/// Output value on mute.
 #[derive(Copy, Clone)]
-pub enum FifoLevel {
+#[allow(missing_docs)]
-    Empty,
-    FirstQuarter,
-    SecondQuarter,
-    ThirdQuarter,
-    FourthQuarter,
-    Full,
-}
-
-#[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-impl From<vals::Flvl> for FifoLevel {
-    fn from(flvl: vals::Flvl) -> Self {
-        match flvl {
-            vals::Flvl::EMPTY => FifoLevel::Empty,
-            vals::Flvl::QUARTER1 => FifoLevel::FirstQuarter,
-            vals::Flvl::QUARTER2 => FifoLevel::SecondQuarter,
-            vals::Flvl::QUARTER3 => FifoLevel::ThirdQuarter,
-            vals::Flvl::QUARTER4 => FifoLevel::FourthQuarter,
-            vals::Flvl::FULL => FifoLevel::Full,
-            _ => FifoLevel::Empty,
-        }
-    }
-}
-
-#[derive(Copy, Clone)]
-pub enum MuteDetection {
-    NoMute,
-    Mute,
-}
-
-#[derive(Copy, Clone)]
 pub enum MuteValue {
     Zero,
     LastValue,
@@ -174,7 +146,7 @@ pub enum MuteValue {
 
 impl MuteValue {
     #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn muteval(&self) -> vals::Muteval {
+    const fn muteval(&self) -> vals::Muteval {
         match self {
             MuteValue::Zero => vals::Muteval::SENDZERO,
             MuteValue::LastValue => vals::Muteval::SENDLAST,
@@ -182,13 +154,9 @@ impl MuteValue {
     }
 }
 
+/// Protocol variant to use.
 #[derive(Copy, Clone)]
-pub enum OverUnderStatus {
+#[allow(missing_docs)]
-    NoError,
-    OverUnderRunDetected,
-}
-
-#[derive(Copy, Clone)]
 pub enum Protocol {
     Free,
     Spdif,
@@ -197,7 +165,7 @@ pub enum Protocol {
 
 impl Protocol {
     #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn prtcfg(&self) -> vals::Prtcfg {
+    const fn prtcfg(&self) -> vals::Prtcfg {
         match self {
             Protocol::Free => vals::Prtcfg::FREE,
             Protocol::Spdif => vals::Prtcfg::SPDIF,
@@ -206,7 +174,9 @@ impl Protocol {
     }
 }
 
+/// Sync input between SAI units/blocks.
 #[derive(Copy, Clone, PartialEq)]
+#[allow(missing_docs)]
 pub enum SyncInput {
     /// Not synced to any other SAI unit.
     None,
@@ -218,7 +188,7 @@ pub enum SyncInput {
 }
 
 impl SyncInput {
-    pub const fn syncen(&self) -> vals::Syncen {
+    const fn syncen(&self) -> vals::Syncen {
         match self {
             SyncInput::None => vals::Syncen::ASYNCHRONOUS,
             SyncInput::Internal => vals::Syncen::INTERNAL,
@@ -228,8 +198,10 @@ impl SyncInput {
     }
 }
 
+/// SAI instance to sync from.
 #[cfg(sai_v4)]
 #[derive(Copy, Clone, PartialEq)]
+#[allow(missing_docs)]
 pub enum SyncInputInstance {
     #[cfg(peri_sai1)]
     Sai1 = 0,
@@ -241,7 +213,9 @@ pub enum SyncInputInstance {
     Sai4 = 3,
 }
 
+/// Channels (stereo or mono).
 #[derive(Copy, Clone, PartialEq)]
+#[allow(missing_docs)]
 pub enum StereoMono {
     Stereo,
     Mono,
@@ -249,7 +223,7 @@ pub enum StereoMono {
 
 impl StereoMono {
     #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn mono(&self) -> vals::Mono {
+    const fn mono(&self) -> vals::Mono {
         match self {
             StereoMono::Stereo => vals::Mono::STEREO,
             StereoMono::Mono => vals::Mono::MONO,
@@ -257,15 +231,18 @@ impl StereoMono {
     }
 }
 
+/// Bit order
 #[derive(Copy, Clone)]
 pub enum BitOrder {
+    /// Least significant bit first.
     LsbFirst,
+    /// Most significant bit first.
     MsbFirst,
 }
 
 impl BitOrder {
     #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn lsbfirst(&self) -> vals::Lsbfirst {
+    const fn lsbfirst(&self) -> vals::Lsbfirst {
         match self {
             BitOrder::LsbFirst => vals::Lsbfirst::LSBFIRST,
             BitOrder::MsbFirst => vals::Lsbfirst::MSBFIRST,
@@ -273,6 +250,7 @@ impl BitOrder {
     }
 }
 
+/// Frame sync offset.
 #[derive(Copy, Clone)]
 pub enum FrameSyncOffset {
     /// This is used in modes other than standard I2S phillips mode
@@ -283,7 +261,7 @@ pub enum FrameSyncOffset {
 
 impl FrameSyncOffset {
     #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn fsoff(&self) -> vals::Fsoff {
+    const fn fsoff(&self) -> vals::Fsoff {
         match self {
             FrameSyncOffset::OnFirstBit => vals::Fsoff::ONFIRST,
             FrameSyncOffset::BeforeFirstBit => vals::Fsoff::BEFOREFIRST,
@@ -291,15 +269,18 @@ impl FrameSyncOffset {
     }
 }
 
+/// Frame sync polarity
 #[derive(Copy, Clone)]
 pub enum FrameSyncPolarity {
+    /// Sync signal is active low.
     ActiveLow,
+    /// Sync signal is active high
     ActiveHigh,
 }
 
 impl FrameSyncPolarity {
     #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn fspol(&self) -> vals::Fspol {
+    const fn fspol(&self) -> vals::Fspol {
         match self {
             FrameSyncPolarity::ActiveLow => vals::Fspol::FALLINGEDGE,
             FrameSyncPolarity::ActiveHigh => vals::Fspol::RISINGEDGE,
@@ -307,7 +288,9 @@ impl FrameSyncPolarity {
     }
 }
 
+/// Sync definition.
 #[derive(Copy, Clone)]
+#[allow(missing_docs)]
 pub enum FrameSyncDefinition {
     StartOfFrame,
     ChannelIdentification,
@@ -315,7 +298,7 @@ pub enum FrameSyncDefinition {
 
 impl FrameSyncDefinition {
     #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn fsdef(&self) -> bool {
+    const fn fsdef(&self) -> bool {
         match self {
             FrameSyncDefinition::StartOfFrame => false,
             FrameSyncDefinition::ChannelIdentification => true,
@@ -323,7 +306,9 @@ impl FrameSyncDefinition {
     }
 }
 
+/// Clock strobe.
 #[derive(Copy, Clone)]
+#[allow(missing_docs)]
 pub enum ClockStrobe {
     Falling,
     Rising,
@@ -331,7 +316,7 @@ pub enum ClockStrobe {
 
 impl ClockStrobe {
     #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn ckstr(&self) -> vals::Ckstr {
+    const fn ckstr(&self) -> vals::Ckstr {
         match self {
             ClockStrobe::Falling => vals::Ckstr::FALLINGEDGE,
             ClockStrobe::Rising => vals::Ckstr::RISINGEDGE,
@@ -339,7 +324,9 @@ impl ClockStrobe {
     }
 }
 
+/// Complements format for negative samples.
 #[derive(Copy, Clone)]
+#[allow(missing_docs)]
 pub enum ComplementFormat {
     OnesComplement,
     TwosComplement,
@@ -347,7 +334,7 @@ pub enum ComplementFormat {
 
 impl ComplementFormat {
     #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn cpl(&self) -> vals::Cpl {
+    const fn cpl(&self) -> vals::Cpl {
         match self {
             ComplementFormat::OnesComplement => vals::Cpl::ONESCOMPLEMENT,
             ComplementFormat::TwosComplement => vals::Cpl::TWOSCOMPLEMENT,
@@ -355,7 +342,9 @@ impl ComplementFormat {
     }
 }
 
+/// Companding setting.
 #[derive(Copy, Clone)]
+#[allow(missing_docs)]
 pub enum Companding {
     None,
     MuLaw,
@@ -364,7 +353,7 @@ pub enum Companding {
 
 impl Companding {
     #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn comp(&self) -> vals::Comp {
+    const fn comp(&self) -> vals::Comp {
         match self {
             Companding::None => vals::Comp::NOCOMPANDING,
             Companding::MuLaw => vals::Comp::MULAW,
@@ -373,7 +362,9 @@ impl Companding {
     }
 }
 
+/// Output drive
 #[derive(Copy, Clone)]
+#[allow(missing_docs)]
 pub enum OutputDrive {
     OnStart,
     Immediately,
@@ -381,7 +372,7 @@ pub enum OutputDrive {
 
 impl OutputDrive {
     #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn outdriv(&self) -> vals::Outdriv {
+    const fn outdriv(&self) -> vals::Outdriv {
         match self {
             OutputDrive::OnStart => vals::Outdriv::ONSTART,
             OutputDrive::Immediately => vals::Outdriv::IMMEDIATELY,
@@ -389,7 +380,9 @@ impl OutputDrive {
     }
 }
 
+/// Master clock divider.
 #[derive(Copy, Clone, PartialEq)]
+#[allow(missing_docs)]
 pub enum MasterClockDivider {
     MasterClockDisabled,
     Div1,
@@ -412,7 +405,7 @@ pub enum MasterClockDivider {
 
 impl MasterClockDivider {
     #[cfg(any(sai_v1, sai_v2, sai_v3, sai_v4))]
-    pub const fn mckdiv(&self) -> u8 {
+    const fn mckdiv(&self) -> u8 {
         match self {
             MasterClockDivider::MasterClockDisabled => 0,
             MasterClockDivider::Div1 => 0,
@@ -436,6 +429,7 @@ impl MasterClockDivider {
 }
 
 /// [`SAI`] configuration.
+#[allow(missing_docs)]
 #[non_exhaustive]
 #[derive(Copy, Clone)]
 pub struct Config {
@@ -459,7 +453,7 @@ pub struct Config {
     pub clock_strobe: ClockStrobe,
     pub output_drive: OutputDrive,
     pub master_clock_divider: MasterClockDivider,
-    pub is_high_impedenane_on_inactive_slot: bool,
+    pub is_high_impedance_on_inactive_slot: bool,
     pub fifo_threshold: FifoThreshold,
     pub companding: Companding,
     pub complement_format: ComplementFormat,
@@ -490,7 +484,7 @@ impl Default for Config {
             master_clock_divider: MasterClockDivider::MasterClockDisabled,
             clock_strobe: ClockStrobe::Rising,
             output_drive: OutputDrive::Immediately,
-            is_high_impedenane_on_inactive_slot: false,
+            is_high_impedance_on_inactive_slot: false,
             fifo_threshold: FifoThreshold::ThreeQuarters,
             companding: Companding::None,
             complement_format: ComplementFormat::TwosComplement,
@@ -501,23 +495,10 @@ impl Default for Config {
 }
 
 impl Config {
-    pub fn new_i2s() -> Self {
+    /// Create a new config with all default values.
+    pub fn new() -> Self {
         return Default::default();
     }
-
-    pub fn new_msb_first() -> Self {
-        Self {
-            bit_order: BitOrder::MsbFirst,
-            frame_sync_offset: FrameSyncOffset::OnFirstBit,
-            ..Default::default()
-        }
-    }
-}
-
-#[derive(Copy, Clone)]
-enum WhichSubBlock {
-    A = 0,
-    B = 1,
 }
 
 enum RingBuffer<'d, C: Channel, W: word::Word> {
@@ -531,28 +512,6 @@ fn dr<W: word::Word>(w: crate::pac::sai::Sai, sub_block: WhichSubBlock) -> *mut
     ch.dr().as_ptr() as _
 }
 
-pub struct SubBlock<'d, T: Instance, C: Channel, W: word::Word> {
-    _peri: PeripheralRef<'d, T>,
-    sd: Option<PeripheralRef<'d, AnyPin>>,
-    fs: Option<PeripheralRef<'d, AnyPin>>,
-    sck: Option<PeripheralRef<'d, AnyPin>>,
-    mclk: Option<PeripheralRef<'d, AnyPin>>,
-    ring_buffer: RingBuffer<'d, C, W>,
-    sub_block: WhichSubBlock,
-}
-
-pub struct SubBlockA {}
-pub struct SubBlockB {}
-
-pub struct SubBlockAPeripheral<'d, T>(PeripheralRef<'d, T>);
-pub struct SubBlockBPeripheral<'d, T>(PeripheralRef<'d, T>);
-
-pub struct Sai<'d, T: Instance> {
-    _peri: PeripheralRef<'d, T>,
-    sub_block_a_peri: Option<SubBlockAPeripheral<'d, T>>,
-    sub_block_b_peri: Option<SubBlockBPeripheral<'d, T>>,
-}
-
 // return the type for (sd, sck)
 fn get_af_types(mode: Mode, tx_rx: TxRx) -> (AFType, AFType) {
     (
@@ -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 {
+/// SAI subblock instance.
-    pub fn new_asynchronous_with_mclk<'d, T: Instance, C: Channel, W: word::Word>(
+pub struct SubBlock<'d, T, S: SubBlockInstance> {
-        peri: SubBlockAPeripheral<'d, T>,
+    peri: PeripheralRef<'d, T>,
-        sck: impl Peripheral<P = impl SckAPin<T>> + 'd,
+    _phantom: PhantomData<S>,
-        sd: impl Peripheral<P = impl SdAPin<T>> + 'd,
+}
-        fs: impl Peripheral<P = impl FsAPin<T>> + 'd,
+
-        mclk: impl Peripheral<P = impl MclkAPin<T>> + 'd,
+/// 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>(
+    /// Create a new SAI driver in asynchronous mode without MCLK.
-        peri: SubBlockAPeripheral<'d, T>,
+    ///
-        sck: impl Peripheral<P = impl SckAPin<T>> + 'd,
+    /// You can obtain the [`SubBlock`] with [`split_subblocks`].
-        sd: impl Peripheral<P = impl SdAPin<T>> + 'd,
+    pub fn new_asynchronous<S: SubBlockInstance>(
-        fs: impl Peripheral<P = impl FsAPin<T>> + 'd,
+        peri: SubBlock<'d, T, S>,
+        sck: impl Peripheral<P = impl SckPin<T, S>> + 'd,
+        sd: impl Peripheral<P = impl SdPin<T, S>> + 'd,
+        fs: impl Peripheral<P = impl FsPin<T, S>> + 'd,
         dma: impl Peripheral<P = C> + 'd,
         dma_buf: &'d mut [W],
         config: Config,
-    ) -> SubBlock<'d, T, C, W>
+    ) -> Self
     where
-        C: Channel + 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>(
+    /// Create a new SAI driver in synchronous mode.
-        peri: SubBlockAPeripheral<'d, T>,
+    ///
-        sd: impl Peripheral<P = impl SdAPin<T>> + 'd,
+    /// You can obtain the [`SubBlock`] with [`split_subblocks`].
+    pub fn new_synchronous<S: SubBlockInstance>(
+        peri: SubBlock<'d, T, S>,
+        sd: impl Peripheral<P = impl SdPin<T, S>> + 'd,
         dma: impl Peripheral<P = C> + 'd,
         dma_buf: &'d mut [W],
         mut config: Config,
-    ) -> SubBlock<'d, T, C, W>
+    ) -> Self
     where
-        C: Channel + 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)]
+    /// Write data to the SAI ringbuffer.
-    /// Reconfigures it with the supplied config.
+    ///
-    fn reconfigure(&mut self, _config: Config) {}
+    /// This appends the data to the buffer and returns immediately. The
-
+    /// data will be transmitted in the background.
-    pub fn get_current_config(&self) -> Config {
+    ///
-        Config::default()
+    /// If there's no space in the buffer, this waits until there is.
-    }
-
     pub async fn write(&mut self, data: &[W]) -> Result<(), Error> {
         match &mut self.ring_buffer {
             RingBuffer::Writable(buffer) => {
@@ -1006,6 +879,12 @@ impl<'d, T: Instance, C: Channel, W: word::Word> SubBlock<'d, T, C, W> {
         }
     }
 
+    /// Read data from the SAI ringbuffer.
+    ///
+    /// SAI is always receiving data in the background. This function pops already-received
+    /// data from the buffer.
+    ///
+    /// If there's less than `data.len()` data in the buffer, this waits until there is.
     pub async fn read(&mut self, data: &mut [W]) -> Result<(), Error> {
         match &mut self.ring_buffer {
             RingBuffer::Readable(buffer) => {
@@ -1017,7 +896,7 @@ impl<'d, T: Instance, C: Channel, W: word::Word> SubBlock<'d, T, C, W> {
     }
 }
 
-impl<'d, T: Instance, C: Channel, W: word::Word> Drop for SubBlock<'d, T, C, W> {
+impl<'d, T: Instance, C: Channel, W: word::Word> Drop for Sai<'d, T, C, W> {
     fn drop(&mut self) {
         let ch = T::REGS.ch(self.sub_block as usize);
         ch.cr1().modify(|w| w.set_saien(false));
@@ -1034,22 +913,43 @@ pub(crate) mod sealed {
     pub trait Instance {
         const REGS: Regs;
     }
+
+    #[derive(Copy, Clone)]
+    pub enum WhichSubBlock {
+        A = 0,
+        B = 1,
+    }
+
+    pub trait SubBlock {
+        const WHICH: WhichSubBlock;
+    }
 }
 
-pub trait Word: word::Word {}
+/// Sub-block instance trait.
+pub trait SubBlockInstance: sealed::SubBlock {}
 
+/// Sub-block A.
+pub enum A {}
+impl sealed::SubBlock for A {
+    const WHICH: WhichSubBlock = WhichSubBlock::A;
+}
+impl SubBlockInstance for A {}
+
+/// Sub-block B.
+pub enum B {}
+impl sealed::SubBlock for B {
+    const WHICH: WhichSubBlock = WhichSubBlock::B;
+}
+impl SubBlockInstance for B {}
+
+/// SAI instance trait.
 pub trait Instance: Peripheral<P = Self> + sealed::Instance + RccPeripheral {}
-pin_trait!(SckAPin, Instance);
+pin_trait!(SckPin, Instance, SubBlockInstance);
-pin_trait!(SckBPin, Instance);
+pin_trait!(FsPin, Instance, SubBlockInstance);
-pin_trait!(FsAPin, Instance);
+pin_trait!(SdPin, Instance, SubBlockInstance);
-pin_trait!(FsBPin, Instance);
+pin_trait!(MclkPin, Instance, SubBlockInstance);
-pin_trait!(SdAPin, Instance);
-pin_trait!(SdBPin, Instance);
-pin_trait!(MclkAPin, Instance);
-pin_trait!(MclkBPin, Instance);
 
-dma_trait!(DmaA, Instance);
+dma_trait!(Dma, Instance, SubBlockInstance);
-dma_trait!(DmaB, Instance);
 
 foreach_peripheral!(
     (sai, $inst:ident) => {
@@ -1060,13 +960,3 @@ foreach_peripheral!(
         impl Instance for peripherals::$inst {}
     };
 );
-
-impl<'d, T: Instance> SetConfig for Sai<'d, T> {
-    type Config = Config;
-    type ConfigError = ();
-    fn set_config(&mut self, _config: &Self::Config) -> Result<(), ()> {
-        // self.reconfigure(*config);
-
-        Ok(())
-    }
-}

embassy-stm32/src/sdmmc/mod.rs

@@ -1,3 +1,4 @@
+//! Secure Digital / MultiMedia Card (SDMMC)
 #![macro_use]
 
 use core::default::Default;
@@ -53,6 +54,7 @@ const SD_INIT_FREQ: Hertz = Hertz(400_000);
 
 /// The signalling scheme used on the SDMMC bus
 #[non_exhaustive]
+#[allow(missing_docs)]
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Signalling {
@@ -69,6 +71,9 @@ impl Default for Signalling {
     }
 }
 
+/// Aligned data block for SDMMC transfers.
+///
+/// This is a 512-byte array, aligned to 4 bytes to satisfy DMA requirements.
 #[repr(align(4))]
 #[derive(Debug, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
@@ -93,17 +98,23 @@ impl DerefMut for DataBlock {
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Error {
+    /// Timeout reported by the hardware
     Timeout,
+    /// Timeout reported by the software driver.
     SoftwareTimeout,
+    /// Unsupported card version.
     UnsupportedCardVersion,
+    /// Unsupported card type.
     UnsupportedCardType,
+    /// CRC error.
     Crc,
-    DataCrcFail,
+    /// No card inserted.
-    RxOverFlow,
     NoCard,
+    /// Bad clock supplied to the SDMMC peripheral.
     BadClock,
+    /// Signaling switch failed.
     SignalingSwitchFailed,
-    PeripheralBusy,
+    /// ST bit error.
     #[cfg(sdmmc_v1)]
     StBitErr,
 }
@@ -282,6 +293,7 @@ pub struct Sdmmc<'d, T: Instance, Dma: SdmmcDma<T> = NoDma> {
 
 #[cfg(sdmmc_v1)]
 impl<'d, T: Instance, Dma: SdmmcDma<T>> Sdmmc<'d, T, Dma> {
+    /// Create a new SDMMC driver, with 1 data lane.
     pub fn new_1bit(
         sdmmc: impl Peripheral<P = T> + 'd,
         _irq: impl interrupt::typelevel::Binding<T::Interrupt, InterruptHandler<T>> + 'd,
@@ -316,6 +328,7 @@ impl<'d, T: Instance, Dma: SdmmcDma<T>> Sdmmc<'d, T, Dma> {
         )
     }
 
+    /// Create a new SDMMC driver, with 4 data lanes.
     pub fn new_4bit(
         sdmmc: impl Peripheral<P = T> + 'd,
         _irq: impl interrupt::typelevel::Binding<T::Interrupt, InterruptHandler<T>> + 'd,
@@ -362,6 +375,7 @@ impl<'d, T: Instance, Dma: SdmmcDma<T>> Sdmmc<'d, T, Dma> {
 
 #[cfg(sdmmc_v2)]
 impl<'d, T: Instance> Sdmmc<'d, T, NoDma> {
+    /// Create a new SDMMC driver, with 1 data lane.
     pub fn new_1bit(
         sdmmc: impl Peripheral<P = T> + 'd,
         _irq: impl interrupt::typelevel::Binding<T::Interrupt, InterruptHandler<T>> + 'd,
@@ -395,6 +409,7 @@ impl<'d, T: Instance> Sdmmc<'d, T, NoDma> {
         )
     }
 
+    /// Create a new SDMMC driver, with 4 data lanes.
     pub fn new_4bit(
         sdmmc: impl Peripheral<P = T> + 'd,
         _irq: impl interrupt::typelevel::Binding<T::Interrupt, InterruptHandler<T>> + 'd,
@@ -496,7 +511,7 @@ impl<'d, T: Instance, Dma: SdmmcDma<T> + 'd> Sdmmc<'d, T, Dma> {
     }
 
     /// Data transfer is in progress
-    #[inline(always)]
+    #[inline]
     fn data_active() -> bool {
         let regs = T::regs();
 
@@ -508,7 +523,7 @@ impl<'d, T: Instance, Dma: SdmmcDma<T> + 'd> Sdmmc<'d, T, Dma> {
     }
 
     /// Coammand transfer is in progress
-    #[inline(always)]
+    #[inline]
     fn cmd_active() -> bool {
         let regs = T::regs();
 
@@ -520,7 +535,7 @@ impl<'d, T: Instance, Dma: SdmmcDma<T> + 'd> Sdmmc<'d, T, Dma> {
     }
 
     /// Wait idle on CMDACT, RXACT and TXACT (v1) or DOSNACT and CPSMACT (v2)
-    #[inline(always)]
+    #[inline]
     fn wait_idle() {
         while Self::data_active() || Self::cmd_active() {}
     }
@@ -836,7 +851,7 @@ impl<'d, T: Instance, Dma: SdmmcDma<T> + 'd> Sdmmc<'d, T, Dma> {
     }
 
     /// Clear flags in interrupt clear register
-    #[inline(always)]
+    #[inline]
     fn clear_interrupt_flags() {
         let regs = T::regs();
         regs.icr().write(|w| {
@@ -1151,7 +1166,8 @@ impl<'d, T: Instance, Dma: SdmmcDma<T> + 'd> Sdmmc<'d, T, Dma> {
         Ok(())
     }
 
-    #[inline(always)]
+    /// Read a data block.
+    #[inline]
     pub async fn read_block(&mut self, block_idx: u32, buffer: &mut DataBlock) -> Result<(), Error> {
         let card_capacity = self.card()?.card_type;
 
@@ -1203,6 +1219,7 @@ impl<'d, T: Instance, Dma: SdmmcDma<T> + 'd> Sdmmc<'d, T, Dma> {
         res
     }
 
+    /// Write a data block.
     pub async fn write_block(&mut self, block_idx: u32, buffer: &DataBlock) -> Result<(), Error> {
         let card = self.card.as_mut().ok_or(Error::NoCard)?;
 
@@ -1282,7 +1299,7 @@ impl<'d, T: Instance, Dma: SdmmcDma<T> + 'd> Sdmmc<'d, T, Dma> {
     ///
     /// Returns Error::NoCard if [`init_card`](#method.init_card)
     /// has not previously succeeded
-    #[inline(always)]
+    #[inline]
     pub fn card(&self) -> Result<&Card, Error> {
         self.card.as_ref().ok_or(Error::NoCard)
     }
@@ -1418,7 +1435,9 @@ pub(crate) mod sealed {
     pub trait Pins<T: Instance> {}
 }
 
+/// SDMMC instance trait.
 pub trait Instance: sealed::Instance + RccPeripheral + 'static {}
+
 pin_trait!(CkPin, Instance);
 pin_trait!(CmdPin, Instance);
 pin_trait!(D0Pin, Instance);
@@ -1433,7 +1452,10 @@ pin_trait!(D7Pin, Instance);
 #[cfg(sdmmc_v1)]
 dma_trait!(SdmmcDma, Instance);
 
-// SDMMCv2 uses internal DMA
+/// DMA instance trait.
+///
+/// This is only implemented for `NoDma`, since SDMMCv2 has DMA built-in, instead of
+/// using ST's system-wide DMA peripheral.
 #[cfg(sdmmc_v2)]
 pub trait SdmmcDma<T: Instance> {}
 #[cfg(sdmmc_v2)]
@@ -1516,53 +1538,3 @@ foreach_peripheral!(
         impl Instance for peripherals::$inst {}
     };
 );
-
-#[cfg(feature = "embedded-sdmmc")]
-mod sdmmc_rs {
-    use embedded_sdmmc::{Block, BlockCount, BlockDevice, BlockIdx};
-
-    use super::*;
-
-    impl<'d, T: Instance, Dma: SdmmcDma<T>> BlockDevice for Sdmmc<'d, T, Dma> {
-        type Error = Error;
-
-        async fn read(
-            &mut self,
-            blocks: &mut [Block],
-            start_block_idx: BlockIdx,
-            _reason: &str,
-        ) -> Result<(), Self::Error> {
-            let mut address = start_block_idx.0;
-
-            for block in blocks.iter_mut() {
-                let block: &mut [u8; 512] = &mut block.contents;
-
-                // NOTE(unsafe) Block uses align(4)
-                let block = unsafe { &mut *(block as *mut _ as *mut DataBlock) };
-                self.read_block(address, block).await?;
-                address += 1;
-            }
-            Ok(())
-        }
-
-        async fn write(&mut self, blocks: &[Block], start_block_idx: BlockIdx) -> Result<(), Self::Error> {
-            let mut address = start_block_idx.0;
-
-            for block in blocks.iter() {
-                let block: &[u8; 512] = &block.contents;
-
-                // NOTE(unsafe) DataBlock uses align 4
-                let block = unsafe { &*(block as *const _ as *const DataBlock) };
-                self.write_block(address, block).await?;
-                address += 1;
-            }
-            Ok(())
-        }
-
-        fn num_blocks(&self) -> Result<BlockCount, Self::Error> {
-            let card = self.card()?;
-            let count = card.csd.block_count();
-            Ok(BlockCount(count))
-        }
-    }
-}

embassy-stm32/src/spi/mod.rs

@@ -1,3 +1,4 @@
+//! Serial Peripheral Interface (SPI)
 #![macro_use]
 
 use core::ptr;
@@ -15,27 +16,38 @@ use crate::rcc::RccPeripheral;
 use crate::time::Hertz;
 use crate::{peripherals, Peripheral};
 
+/// SPI error.
 #[derive(Debug, PartialEq, Eq)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Error {
+    /// Invalid framing.
     Framing,
+    /// CRC error (only if hardware CRC checking is enabled).
     Crc,
+    /// Mode fault
     ModeFault,
+    /// Overrun.
     Overrun,
 }
 
-// TODO move upwards in the tree
+/// SPI bit order
 #[derive(Copy, Clone)]
 pub enum BitOrder {
+    /// Least significant bit first.
     LsbFirst,
+    /// Most significant bit first.
     MsbFirst,
 }
 
+/// SPI configuration.
 #[non_exhaustive]
 #[derive(Copy, Clone)]
 pub struct Config {
+    /// SPI mode.
     pub mode: Mode,
+    /// Bit order.
     pub bit_order: BitOrder,
+    /// Clock frequency.
     pub frequency: Hertz,
 }
 
@@ -72,6 +84,7 @@ impl Config {
     }
 }
 
+/// SPI driver.
 pub struct Spi<'d, T: Instance, Tx, Rx> {
     _peri: PeripheralRef<'d, T>,
     sck: Option<PeripheralRef<'d, AnyPin>>,
@@ -83,6 +96,7 @@ pub struct Spi<'d, T: Instance, Tx, Rx> {
 }
 
 impl<'d, T: Instance, Tx, Rx> Spi<'d, T, Tx, Rx> {
+    /// Create a new SPI driver.
     pub fn new(
         peri: impl Peripheral<P = T> + 'd,
         sck: impl Peripheral<P = impl SckPin<T>> + 'd,
@@ -117,6 +131,7 @@ impl<'d, T: Instance, Tx, Rx> Spi<'d, T, Tx, Rx> {
         )
     }
 
+    /// Create a new SPI driver, in RX-only mode (only MISO pin, no MOSI).
     pub fn new_rxonly(
         peri: impl Peripheral<P = T> + 'd,
         sck: impl Peripheral<P = impl SckPin<T>> + 'd,
@@ -142,6 +157,7 @@ impl<'d, T: Instance, Tx, Rx> Spi<'d, T, Tx, Rx> {
         )
     }
 
+    /// Create a new SPI driver, in TX-only mode (only MOSI pin, no MISO).
     pub fn new_txonly(
         peri: impl Peripheral<P = T> + 'd,
         sck: impl Peripheral<P = impl SckPin<T>> + 'd,
@@ -167,6 +183,9 @@ impl<'d, T: Instance, Tx, Rx> Spi<'d, T, Tx, Rx> {
         )
     }
 
+    /// Create a new SPI driver, in TX-only mode, without SCK pin.
+    ///
+    /// This can be useful for bit-banging non-SPI protocols.
     pub fn new_txonly_nosck(
         peri: impl Peripheral<P = T> + 'd,
         mosi: impl Peripheral<P = impl MosiPin<T>> + 'd,
@@ -354,6 +373,7 @@ impl<'d, T: Instance, Tx, Rx> Spi<'d, T, Tx, Rx> {
         Ok(())
     }
 
+    /// Get current SPI configuration.
     pub fn get_current_config(&self) -> Config {
         #[cfg(any(spi_v1, spi_f1, spi_v2))]
         let cfg = T::REGS.cr1().read();
@@ -443,6 +463,7 @@ impl<'d, T: Instance, Tx, Rx> Spi<'d, T, Tx, Rx> {
         self.current_word_size = word_size;
     }
 
+    /// SPI write, using DMA.
     pub async fn write<W: Word>(&mut self, data: &[W]) -> Result<(), Error>
     where
         Tx: TxDma<T>,
@@ -476,6 +497,7 @@ impl<'d, T: Instance, Tx, Rx> Spi<'d, T, Tx, Rx> {
         Ok(())
     }
 
+    /// SPI read, using DMA.
     pub async fn read<W: Word>(&mut self, data: &mut [W]) -> Result<(), Error>
     where
         Tx: TxDma<T>,
@@ -579,6 +601,12 @@ impl<'d, T: Instance, Tx, Rx> Spi<'d, T, Tx, Rx> {
         Ok(())
     }
 
+    /// Bidirectional transfer, using DMA.
+    ///
+    /// This transfers both buffers at the same time, so it is NOT equivalent to `write` followed by `read`.
+    ///
+    /// The transfer runs for `max(read.len(), write.len())` bytes. If `read` is shorter extra bytes are ignored.
+    /// If `write` is shorter it is padded with zero bytes.
     pub async fn transfer<W: Word>(&mut self, read: &mut [W], write: &[W]) -> Result<(), Error>
     where
         Tx: TxDma<T>,
@@ -587,6 +615,9 @@ impl<'d, T: Instance, Tx, Rx> Spi<'d, T, Tx, Rx> {
         self.transfer_inner(read, write).await
     }
 
+    /// In-place bidirectional transfer, using DMA.
+    ///
+    /// This writes the contents of `data` on MOSI, and puts the received data on MISO in `data`, at the same time.
     pub async fn transfer_in_place<W: Word>(&mut self, data: &mut [W]) -> Result<(), Error>
     where
         Tx: TxDma<T>,
@@ -595,6 +626,7 @@ impl<'d, T: Instance, Tx, Rx> Spi<'d, T, Tx, Rx> {
         self.transfer_inner(data, data).await
     }
 
+    /// Blocking write.
     pub fn blocking_write<W: Word>(&mut self, words: &[W]) -> Result<(), Error> {
         T::REGS.cr1().modify(|w| w.set_spe(true));
         flush_rx_fifo(T::REGS);
@@ -605,6 +637,7 @@ impl<'d, T: Instance, Tx, Rx> Spi<'d, T, Tx, Rx> {
         Ok(())
     }
 
+    /// Blocking read.
     pub fn blocking_read<W: Word>(&mut self, words: &mut [W]) -> Result<(), Error> {
         T::REGS.cr1().modify(|w| w.set_spe(true));
         flush_rx_fifo(T::REGS);
@@ -615,6 +648,9 @@ impl<'d, T: Instance, Tx, Rx> Spi<'d, T, Tx, Rx> {
         Ok(())
     }
 
+    /// Blocking in-place bidirectional transfer.
+    ///
+    /// This writes the contents of `data` on MOSI, and puts the received data on MISO in `data`, at the same time.
     pub fn blocking_transfer_in_place<W: Word>(&mut self, words: &mut [W]) -> Result<(), Error> {
         T::REGS.cr1().modify(|w| w.set_spe(true));
         flush_rx_fifo(T::REGS);
@@ -625,6 +661,12 @@ impl<'d, T: Instance, Tx, Rx> Spi<'d, T, Tx, Rx> {
         Ok(())
     }
 
+    /// Blocking bidirectional transfer.
+    ///
+    /// This transfers both buffers at the same time, so it is NOT equivalent to `write` followed by `read`.
+    ///
+    /// The transfer runs for `max(read.len(), write.len())` bytes. If `read` is shorter extra bytes are ignored.
+    /// If `write` is shorter it is padded with zero bytes.
     pub fn blocking_transfer<W: Word>(&mut self, read: &mut [W], write: &[W]) -> Result<(), Error> {
         T::REGS.cr1().modify(|w| w.set_spe(true));
         flush_rx_fifo(T::REGS);
@@ -945,6 +987,7 @@ pub(crate) mod sealed {
     }
 }
 
+/// Word sizes usable for SPI.
 pub trait Word: word::Word + sealed::Word {}
 
 macro_rules! impl_word {
@@ -1024,7 +1067,9 @@ mod word_impl {
     impl_word!(u32, 32 - 1);
 }
 
+/// SPI instance trait.
 pub trait Instance: Peripheral<P = Self> + sealed::Instance + RccPeripheral {}
+
 pin_trait!(SckPin, Instance);
 pin_trait!(MosiPin, Instance);
 pin_trait!(MisoPin, Instance);

embassy-stm32/src/time.rs

@@ -8,14 +8,17 @@ use core::ops::{Div, Mul};
 pub struct Hertz(pub u32);
 
 impl Hertz {
+    /// Create a `Hertz` from the given hertz.
     pub const fn hz(hertz: u32) -> Self {
         Self(hertz)
     }
 
+    /// Create a `Hertz` from the given kilohertz.
     pub const fn khz(kilohertz: u32) -> Self {
         Self(kilohertz * 1_000)
     }
 
+    /// Create a `Hertz` from the given megahertz.
     pub const fn mhz(megahertz: u32) -> Self {
         Self(megahertz * 1_000_000)
     }

embassy-stm32/src/timer/complementary_pwm.rs

@@ -13,15 +13,19 @@ use crate::gpio::{AnyPin, OutputType};
 use crate::time::Hertz;
 use crate::Peripheral;
 
-pub struct ComplementaryPwmPin<'d, Perip, Channel> {
+/// Complementary PWM pin wrapper.
+///
+/// This wraps a pin to make it usable with PWM.
+pub struct ComplementaryPwmPin<'d, T, C> {
     _pin: PeripheralRef<'d, AnyPin>,
-    phantom: PhantomData<(Perip, Channel)>,
+    phantom: PhantomData<(T, C)>,
 }
 
 macro_rules! complementary_channel_impl {
     ($new_chx:ident, $channel:ident, $pin_trait:ident) => {
-        impl<'d, Perip: CaptureCompare16bitInstance> ComplementaryPwmPin<'d, Perip, $channel> {
+        impl<'d, T: CaptureCompare16bitInstance> ComplementaryPwmPin<'d, T, $channel> {
-            pub fn $new_chx(pin: impl Peripheral<P = impl $pin_trait<Perip>> + 'd, output_type: OutputType) -> Self {
+            #[doc = concat!("Create a new ", stringify!($channel), " complementary PWM pin instance.")]
+            pub fn $new_chx(pin: impl Peripheral<P = impl $pin_trait<T>> + 'd, output_type: OutputType) -> Self {
                 into_ref!(pin);
                 critical_section::with(|_| {
                     pin.set_low();
@@ -43,11 +47,13 @@ complementary_channel_impl!(new_ch2, Ch2, Channel2ComplementaryPin);
 complementary_channel_impl!(new_ch3, Ch3, Channel3ComplementaryPin);
 complementary_channel_impl!(new_ch4, Ch4, Channel4ComplementaryPin);
 
+/// PWM driver with support for standard and complementary outputs.
 pub struct ComplementaryPwm<'d, T> {
     inner: PeripheralRef<'d, T>,
 }
 
 impl<'d, T: ComplementaryCaptureCompare16bitInstance> ComplementaryPwm<'d, T> {
+    /// Create a new complementary PWM driver.
     pub fn new(
         tim: impl Peripheral<P = T> + 'd,
         _ch1: Option<PwmPin<'d, T, Ch1>>,
@@ -72,7 +78,7 @@ impl<'d, T: ComplementaryCaptureCompare16bitInstance> ComplementaryPwm<'d, T> {
         let mut this = Self { inner: tim };
 
         this.inner.set_counting_mode(counting_mode);
-        this.set_freq(freq);
+        this.set_frequency(freq);
         this.inner.start();
 
         this.inner.enable_outputs();
@@ -88,17 +94,23 @@ impl<'d, T: ComplementaryCaptureCompare16bitInstance> ComplementaryPwm<'d, T> {
         this
     }
 
+    /// Enable the given channel.
     pub fn enable(&mut self, channel: Channel) {
         self.inner.enable_channel(channel, true);
         self.inner.enable_complementary_channel(channel, true);
     }
 
+    /// Disable the given channel.
     pub fn disable(&mut self, channel: Channel) {
         self.inner.enable_complementary_channel(channel, false);
         self.inner.enable_channel(channel, false);
     }
 
-    pub fn set_freq(&mut self, freq: Hertz) {
+    /// Set PWM frequency.
+    ///
+    /// Note: when you call this, the max duty value changes, so you will have to
+    /// call `set_duty` on all channels with the duty calculated based on the new max duty.
+    pub fn set_frequency(&mut self, freq: Hertz) {
         let multiplier = if self.inner.get_counting_mode().is_center_aligned() {
             2u8
         } else {
@@ -107,15 +119,22 @@ impl<'d, T: ComplementaryCaptureCompare16bitInstance> ComplementaryPwm<'d, T> {
         self.inner.set_frequency(freq * multiplier);
     }
 
+    /// Get max duty value.
+    ///
+    /// This value depends on the configured frequency and the timer's clock rate from RCC.
     pub fn get_max_duty(&self) -> u16 {
         self.inner.get_max_compare_value() + 1
     }
 
+    /// Set the duty for a given channel.
+    ///
+    /// The value ranges from 0 for 0% duty, to [`get_max_duty`](Self::get_max_duty) for 100% duty, both included.
     pub fn set_duty(&mut self, channel: Channel, duty: u16) {
         assert!(duty <= self.get_max_duty());
         self.inner.set_compare_value(channel, duty)
     }
 
+    /// Set the output polarity for a given channel.
     pub fn set_polarity(&mut self, channel: Channel, polarity: OutputPolarity) {
         self.inner.set_output_polarity(channel, polarity);
         self.inner.set_complementary_output_polarity(channel, polarity);

embassy-stm32/src/timer/mod.rs

@@ -17,17 +17,27 @@ pub mod low_level {
 }
 
 pub(crate) mod sealed {
-
     use super::*;
+
+    /// Basic 16-bit timer instance.
     pub trait Basic16bitInstance: RccPeripheral {
+        /// Interrupt for this timer.
         type Interrupt: interrupt::typelevel::Interrupt;
 
+        /// Get access to the basic 16bit timer registers.
+        ///
+        /// Note: This works even if the timer is more capable, because registers
+        /// for the less capable timers are a subset. This allows writing a driver
+        /// for a given set of capabilities, and having it transparently work with
+        /// more capable timers.
         fn regs() -> crate::pac::timer::TimBasic;
 
+        /// Start the timer.
         fn start(&mut self) {
             Self::regs().cr1().modify(|r| r.set_cen(true));
         }
 
+        /// Stop the timer.
         fn stop(&mut self) {
             Self::regs().cr1().modify(|r| r.set_cen(false));
         }
@@ -63,6 +73,9 @@ pub(crate) mod sealed {
             regs.cr1().modify(|r| r.set_urs(vals::Urs::ANYEVENT));
         }
 
+        /// Clear update interrupt.
+        ///
+        /// Returns whether the update interrupt flag was set.
         fn clear_update_interrupt(&mut self) -> bool {
             let regs = Self::regs();
             let sr = regs.sr().read();
@@ -76,14 +89,17 @@ pub(crate) mod sealed {
             }
         }
 
+        /// Enable/disable the update interrupt.
         fn enable_update_interrupt(&mut self, enable: bool) {
             Self::regs().dier().write(|r| r.set_uie(enable));
         }
 
+        /// Enable/disable autoreload preload.
         fn set_autoreload_preload(&mut self, enable: bool) {
             Self::regs().cr1().modify(|r| r.set_arpe(enable));
         }
 
+        /// Get the timer frequency.
         fn get_frequency(&self) -> Hertz {
             let timer_f = Self::frequency();
 
@@ -95,9 +111,17 @@ pub(crate) mod sealed {
         }
     }
 
+    /// Gneral-purpose 16-bit timer instance.
     pub trait GeneralPurpose16bitInstance: Basic16bitInstance {
+        /// Get access to the general purpose 16bit timer registers.
+        ///
+        /// Note: This works even if the timer is more capable, because registers
+        /// for the less capable timers are a subset. This allows writing a driver
+        /// for a given set of capabilities, and having it transparently work with
+        /// more capable timers.
         fn regs_gp16() -> crate::pac::timer::TimGp16;
 
+        /// Set counting mode.
         fn set_counting_mode(&mut self, mode: CountingMode) {
             let (cms, dir) = mode.into();
 
@@ -110,19 +134,29 @@ pub(crate) mod sealed {
             Self::regs_gp16().cr1().modify(|r| r.set_cms(cms))
         }
 
+        /// Get counting mode.
         fn get_counting_mode(&self) -> CountingMode {
             let cr1 = Self::regs_gp16().cr1().read();
             (cr1.cms(), cr1.dir()).into()
         }
 
+        /// Set clock divider.
         fn set_clock_division(&mut self, ckd: vals::Ckd) {
             Self::regs_gp16().cr1().modify(|r| r.set_ckd(ckd));
         }
     }
 
+    /// Gneral-purpose 32-bit timer instance.
     pub trait GeneralPurpose32bitInstance: GeneralPurpose16bitInstance {
+        /// Get access to the general purpose 32bit timer registers.
+        ///
+        /// Note: This works even if the timer is more capable, because registers
+        /// for the less capable timers are a subset. This allows writing a driver
+        /// for a given set of capabilities, and having it transparently work with
+        /// more capable timers.
         fn regs_gp32() -> crate::pac::timer::TimGp32;
 
+        /// Set timer frequency.
         fn set_frequency(&mut self, frequency: Hertz) {
             let f = frequency.0;
             assert!(f > 0);
@@ -140,6 +174,7 @@ pub(crate) mod sealed {
             regs.cr1().modify(|r| r.set_urs(vals::Urs::ANYEVENT));
         }
 
+        /// Get timer frequency.
         fn get_frequency(&self) -> Hertz {
             let timer_f = Self::frequency();
 
@@ -151,141 +186,177 @@ pub(crate) mod sealed {
         }
     }
 
+    /// Advanced control timer instance.
     pub trait AdvancedControlInstance: GeneralPurpose16bitInstance {
+        /// Get access to the advanced timer registers.
         fn regs_advanced() -> crate::pac::timer::TimAdv;
     }
 
+    /// Capture/Compare 16-bit timer instance.
     pub trait CaptureCompare16bitInstance: GeneralPurpose16bitInstance {
+        /// Set input capture filter.
         fn set_input_capture_filter(&mut self, channel: Channel, icf: vals::Icf) {
-            let raw_channel = channel.raw();
+            let raw_channel = channel.index();
             Self::regs_gp16()
                 .ccmr_input(raw_channel / 2)
                 .modify(|r| r.set_icf(raw_channel % 2, icf));
         }
 
+        /// Clear input interrupt.
         fn clear_input_interrupt(&mut self, channel: Channel) {
-            Self::regs_gp16().sr().modify(|r| r.set_ccif(channel.raw(), false));
+            Self::regs_gp16().sr().modify(|r| r.set_ccif(channel.index(), false));
         }
 
+        /// Enable input interrupt.
         fn enable_input_interrupt(&mut self, channel: Channel, enable: bool) {
-            Self::regs_gp16().dier().modify(|r| r.set_ccie(channel.raw(), enable));
+            Self::regs_gp16().dier().modify(|r| r.set_ccie(channel.index(), enable));
         }
+
+        /// Set input capture prescaler.
         fn set_input_capture_prescaler(&mut self, channel: Channel, factor: u8) {
-            let raw_channel = channel.raw();
+            let raw_channel = channel.index();
             Self::regs_gp16()
                 .ccmr_input(raw_channel / 2)
                 .modify(|r| r.set_icpsc(raw_channel % 2, factor));
         }
 
+        /// Set input TI selection.
         fn set_input_ti_selection(&mut self, channel: Channel, tisel: InputTISelection) {
-            let raw_channel = channel.raw();
+            let raw_channel = channel.index();
             Self::regs_gp16()
                 .ccmr_input(raw_channel / 2)
                 .modify(|r| r.set_ccs(raw_channel % 2, tisel.into()));
         }
+
+        /// Set input capture mode.
         fn set_input_capture_mode(&mut self, channel: Channel, mode: InputCaptureMode) {
             Self::regs_gp16().ccer().modify(|r| match mode {
                 InputCaptureMode::Rising => {
-                    r.set_ccnp(channel.raw(), false);
+                    r.set_ccnp(channel.index(), false);
-                    r.set_ccp(channel.raw(), false);
+                    r.set_ccp(channel.index(), false);
                 }
                 InputCaptureMode::Falling => {
-                    r.set_ccnp(channel.raw(), false);
+                    r.set_ccnp(channel.index(), false);
-                    r.set_ccp(channel.raw(), true);
+                    r.set_ccp(channel.index(), true);
                 }
                 InputCaptureMode::BothEdges => {
-                    r.set_ccnp(channel.raw(), true);
+                    r.set_ccnp(channel.index(), true);
-                    r.set_ccp(channel.raw(), true);
+                    r.set_ccp(channel.index(), true);
                 }
             });
         }
+
+        /// Enable timer outputs.
         fn enable_outputs(&mut self);
 
+        /// Set output compare mode.
         fn set_output_compare_mode(&mut self, channel: Channel, mode: OutputCompareMode) {
             let r = Self::regs_gp16();
-            let raw_channel: usize = channel.raw();
+            let raw_channel: usize = channel.index();
             r.ccmr_output(raw_channel / 2)
                 .modify(|w| w.set_ocm(raw_channel % 2, mode.into()));
         }
 
+        /// Set output polarity.
         fn set_output_polarity(&mut self, channel: Channel, polarity: OutputPolarity) {
             Self::regs_gp16()
                 .ccer()
-                .modify(|w| w.set_ccp(channel.raw(), polarity.into()));
+                .modify(|w| w.set_ccp(channel.index(), polarity.into()));
         }
 
+        /// Enable/disable a channel.
         fn enable_channel(&mut self, channel: Channel, enable: bool) {
-            Self::regs_gp16().ccer().modify(|w| w.set_cce(channel.raw(), enable));
+            Self::regs_gp16().ccer().modify(|w| w.set_cce(channel.index(), enable));
         }
 
+        /// Set compare value for a channel.
         fn set_compare_value(&mut self, channel: Channel, value: u16) {
-            Self::regs_gp16().ccr(channel.raw()).modify(|w| w.set_ccr(value));
+            Self::regs_gp16().ccr(channel.index()).modify(|w| w.set_ccr(value));
         }
 
+        /// Get capture value for a channel.
         fn get_capture_value(&mut self, channel: Channel) -> u16 {
-            Self::regs_gp16().ccr(channel.raw()).read().ccr()
+            Self::regs_gp16().ccr(channel.index()).read().ccr()
         }
 
+        /// Get max compare value. This depends on the timer frequency and the clock frequency from RCC.
         fn get_max_compare_value(&self) -> u16 {
             Self::regs_gp16().arr().read().arr()
         }
 
+        /// Get compare value for a channel.
         fn get_compare_value(&self, channel: Channel) -> u16 {
-            Self::regs_gp16().ccr(channel.raw()).read().ccr()
+            Self::regs_gp16().ccr(channel.index()).read().ccr()
         }
     }
 
+    /// Capture/Compare 16-bit timer instance with complementary pin support.
     pub trait ComplementaryCaptureCompare16bitInstance: CaptureCompare16bitInstance + AdvancedControlInstance {
+        /// Set complementary output polarity.
         fn set_complementary_output_polarity(&mut self, channel: Channel, polarity: OutputPolarity) {
             Self::regs_advanced()
                 .ccer()
-                .modify(|w| w.set_ccnp(channel.raw(), polarity.into()));
+                .modify(|w| w.set_ccnp(channel.index(), polarity.into()));
         }
 
+        /// Set clock divider for the dead time.
         fn set_dead_time_clock_division(&mut self, value: vals::Ckd) {
             Self::regs_advanced().cr1().modify(|w| w.set_ckd(value));
         }
 
+        /// Set dead time, as a fraction of the max duty value.
         fn set_dead_time_value(&mut self, value: u8) {
             Self::regs_advanced().bdtr().modify(|w| w.set_dtg(value));
         }
 
+        /// Enable/disable a complementary channel.
         fn enable_complementary_channel(&mut self, channel: Channel, enable: bool) {
             Self::regs_advanced()
                 .ccer()
-                .modify(|w| w.set_ccne(channel.raw(), enable));
+                .modify(|w| w.set_ccne(channel.index(), enable));
         }
     }
 
+    /// Capture/Compare 32-bit timer instance.
     pub trait CaptureCompare32bitInstance: GeneralPurpose32bitInstance + CaptureCompare16bitInstance {
+        /// Set comapre value for a channel.
         fn set_compare_value(&mut self, channel: Channel, value: u32) {
-            Self::regs_gp32().ccr(channel.raw()).modify(|w| w.set_ccr(value));
+            Self::regs_gp32().ccr(channel.index()).modify(|w| w.set_ccr(value));
         }
 
+        /// Get capture value for a channel.
         fn get_capture_value(&mut self, channel: Channel) -> u32 {
-            Self::regs_gp32().ccr(channel.raw()).read().ccr()
+            Self::regs_gp32().ccr(channel.index()).read().ccr()
         }
 
+        /// Get max compare value. This depends on the timer frequency and the clock frequency from RCC.
         fn get_max_compare_value(&self) -> u32 {
             Self::regs_gp32().arr().read().arr()
         }
 
+        /// Get compare value for a channel.
         fn get_compare_value(&self, channel: Channel) -> u32 {
-            Self::regs_gp32().ccr(channel.raw()).read().ccr()
+            Self::regs_gp32().ccr(channel.index()).read().ccr()
         }
     }
 }
 
+/// Timer channel.
 #[derive(Clone, Copy)]
 pub enum Channel {
+    /// Channel 1.
     Ch1,
+    /// Channel 2.
     Ch2,
+    /// Channel 3.
     Ch3,
+    /// Channel 4.
     Ch4,
 }
 
 impl Channel {
-    pub fn raw(&self) -> usize {
+    /// Get the channel index (0..3)
+    pub fn index(&self) -> usize {
         match self {
             Channel::Ch1 => 0,
             Channel::Ch2 => 1,
@@ -295,17 +366,25 @@ impl Channel {
     }
 }
 
+/// Input capture mode.
 #[derive(Clone, Copy)]
 pub enum InputCaptureMode {
+    /// Rising edge only.
     Rising,
+    /// Falling edge only.
     Falling,
+    /// Both rising or falling edges.
     BothEdges,
 }
 
+/// Input TI selection.
 #[derive(Clone, Copy)]
 pub enum InputTISelection {
+    /// Normal
     Normal,
+    /// Alternate
     Alternate,
+    /// TRC
     TRC,
 }
 
@@ -319,6 +398,7 @@ impl From<InputTISelection> for stm32_metapac::timer::vals::CcmrInputCcs {
     }
 }
 
+/// Timer counting mode.
 #[repr(u8)]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
 pub enum CountingMode {
@@ -345,6 +425,7 @@ pub enum CountingMode {
 }
 
 impl CountingMode {
+    /// Return whether this mode is edge-aligned (up or down).
     pub fn is_edge_aligned(&self) -> bool {
         match self {
             CountingMode::EdgeAlignedUp | CountingMode::EdgeAlignedDown => true,
@@ -352,6 +433,7 @@ impl CountingMode {
         }
     }
 
+    /// Return whether this mode is center-aligned.
     pub fn is_center_aligned(&self) -> bool {
         match self {
             CountingMode::CenterAlignedDownInterrupts
@@ -386,16 +468,34 @@ impl From<(vals::Cms, vals::Dir)> for CountingMode {
     }
 }
 
+/// Output compare mode.
 #[derive(Clone, Copy)]
 pub enum OutputCompareMode {
+    /// The comparison between the output compare register TIMx_CCRx and
+    /// the counter TIMx_CNT has no effect on the outputs.
+    /// (this mode is used to generate a timing base).
     Frozen,
+    /// Set channel to active level on match. OCxREF signal is forced high when the
+    /// counter TIMx_CNT matches the capture/compare register x (TIMx_CCRx).
     ActiveOnMatch,
+    /// Set channel to inactive level on match. OCxREF signal is forced low when the
+    /// counter TIMx_CNT matches the capture/compare register x (TIMx_CCRx).
     InactiveOnMatch,
+    /// Toggle - OCxREF toggles when TIMx_CNT=TIMx_CCRx.
     Toggle,
+    /// Force inactive level - OCxREF is forced low.
     ForceInactive,
+    /// Force active level - OCxREF is forced high.
     ForceActive,
+    /// PWM mode 1 - In upcounting, channel is active as long as TIMx_CNT<TIMx_CCRx
+    /// else inactive. In downcounting, channel is inactive (OCxREF=0) as long as
+    /// TIMx_CNT>TIMx_CCRx else active (OCxREF=1).
     PwmMode1,
+    /// PWM mode 2 - In upcounting, channel is inactive as long as
+    /// TIMx_CNT<TIMx_CCRx else active. In downcounting, channel is active as long as
+    /// TIMx_CNT>TIMx_CCRx else inactive.
     PwmMode2,
+    // TODO: there's more modes here depending on the chip family.
 }
 
 impl From<OutputCompareMode> for stm32_metapac::timer::vals::Ocm {
@@ -413,9 +513,12 @@ impl From<OutputCompareMode> for stm32_metapac::timer::vals::Ocm {
     }
 }
 
+/// Timer output pin polarity.
 #[derive(Clone, Copy)]
 pub enum OutputPolarity {
+    /// Active high (higher duty value makes the pin spend more time high).
     ActiveHigh,
+    /// Active low (higher duty value makes the pin spend more time low).
     ActiveLow,
 }
 
@@ -428,24 +531,31 @@ impl From<OutputPolarity> for bool {
     }
 }
 
+/// Basic 16-bit timer instance.
 pub trait Basic16bitInstance: sealed::Basic16bitInstance + 'static {}
 
+/// Gneral-purpose 16-bit timer instance.
 pub trait GeneralPurpose16bitInstance: sealed::GeneralPurpose16bitInstance + 'static {}
 
+/// Gneral-purpose 32-bit timer instance.
 pub trait GeneralPurpose32bitInstance: sealed::GeneralPurpose32bitInstance + 'static {}
 
+/// Advanced control timer instance.
 pub trait AdvancedControlInstance: sealed::AdvancedControlInstance + 'static {}
 
+/// Capture/Compare 16-bit timer instance.
 pub trait CaptureCompare16bitInstance:
     sealed::CaptureCompare16bitInstance + GeneralPurpose16bitInstance + 'static
 {
 }
 
+/// Capture/Compare 16-bit timer instance with complementary pin support.
 pub trait ComplementaryCaptureCompare16bitInstance:
     sealed::ComplementaryCaptureCompare16bitInstance + AdvancedControlInstance + 'static
 {
 }
 
+/// Capture/Compare 32-bit timer instance.
 pub trait CaptureCompare32bitInstance:
     sealed::CaptureCompare32bitInstance + CaptureCompare16bitInstance + GeneralPurpose32bitInstance + 'static
 {

embassy-stm32/src/timer/qei.rs

@@ -9,23 +9,30 @@ use crate::gpio::sealed::AFType;
 use crate::gpio::AnyPin;
 use crate::Peripheral;
 
+/// Counting direction
 pub enum Direction {
+    /// Counting up.
     Upcounting,
+    /// Counting down.
     Downcounting,
 }
 
-pub struct Ch1;
+/// Channel 1 marker type.
-pub struct Ch2;
+pub enum Ch1 {}
+/// Channel 2 marker type.
+pub enum Ch2 {}
 
-pub struct QeiPin<'d, Perip, Channel> {
+/// Wrapper for using a pin with QEI.
+pub struct QeiPin<'d, T, Channel> {
     _pin: PeripheralRef<'d, AnyPin>,
-    phantom: PhantomData<(Perip, Channel)>,
+    phantom: PhantomData<(T, Channel)>,
 }
 
 macro_rules! channel_impl {
     ($new_chx:ident, $channel:ident, $pin_trait:ident) => {
-        impl<'d, Perip: CaptureCompare16bitInstance> QeiPin<'d, Perip, $channel> {
+        impl<'d, T: CaptureCompare16bitInstance> QeiPin<'d, T, $channel> {
-            pub fn $new_chx(pin: impl Peripheral<P = impl $pin_trait<Perip>> + 'd) -> Self {
+            #[doc = concat!("Create a new ", stringify!($channel), " QEI pin instance.")]
+            pub fn $new_chx(pin: impl Peripheral<P = impl $pin_trait<T>> + 'd) -> Self {
                 into_ref!(pin);
                 critical_section::with(|_| {
                     pin.set_low();
@@ -45,11 +52,13 @@ macro_rules! channel_impl {
 channel_impl!(new_ch1, Ch1, Channel1Pin);
 channel_impl!(new_ch2, Ch2, Channel2Pin);
 
+/// Quadrature decoder driver.
 pub struct Qei<'d, T> {
     _inner: PeripheralRef<'d, T>,
 }
 
 impl<'d, T: CaptureCompare16bitInstance> Qei<'d, T> {
+    /// Create a new quadrature decoder driver.
     pub fn new(tim: impl Peripheral<P = T> + 'd, _ch1: QeiPin<'d, T, Ch1>, _ch2: QeiPin<'d, T, Ch2>) -> Self {
         Self::new_inner(tim)
     }
@@ -84,6 +93,7 @@ impl<'d, T: CaptureCompare16bitInstance> Qei<'d, T> {
         Self { _inner: tim }
     }
 
+    /// Get direction.
     pub fn read_direction(&self) -> Direction {
         match T::regs_gp16().cr1().read().dir() {
             vals::Dir::DOWN => Direction::Downcounting,
@@ -91,6 +101,7 @@ impl<'d, T: CaptureCompare16bitInstance> Qei<'d, T> {
         }
     }
 
+    /// Get count.
     pub fn count(&self) -> u16 {
         T::regs_gp16().cnt().read().cnt()
     }

embassy-stm32/src/timer/simple_pwm.rs

@@ -11,20 +11,28 @@ use crate::gpio::{AnyPin, OutputType};
 use crate::time::Hertz;
 use crate::Peripheral;
 
-pub struct Ch1;
+/// Channel 1 marker type.
-pub struct Ch2;
+pub enum Ch1 {}
-pub struct Ch3;
+/// Channel 2 marker type.
-pub struct Ch4;
+pub enum Ch2 {}
+/// Channel 3 marker type.
+pub enum Ch3 {}
+/// Channel 4 marker type.
+pub enum Ch4 {}
 
-pub struct PwmPin<'d, Perip, Channel> {
+/// PWM pin wrapper.
+///
+/// This wraps a pin to make it usable with PWM.
+pub struct PwmPin<'d, T, C> {
     _pin: PeripheralRef<'d, AnyPin>,
-    phantom: PhantomData<(Perip, Channel)>,
+    phantom: PhantomData<(T, C)>,
 }
 
 macro_rules! channel_impl {
     ($new_chx:ident, $channel:ident, $pin_trait:ident) => {
-        impl<'d, Perip: CaptureCompare16bitInstance> PwmPin<'d, Perip, $channel> {
+        impl<'d, T: CaptureCompare16bitInstance> PwmPin<'d, T, $channel> {
-            pub fn $new_chx(pin: impl Peripheral<P = impl $pin_trait<Perip>> + 'd, output_type: OutputType) -> Self {
+            #[doc = concat!("Create a new ", stringify!($channel), " PWM pin instance.")]
+            pub fn $new_chx(pin: impl Peripheral<P = impl $pin_trait<T>> + 'd, output_type: OutputType) -> Self {
                 into_ref!(pin);
                 critical_section::with(|_| {
                     pin.set_low();
@@ -46,11 +54,13 @@ channel_impl!(new_ch2, Ch2, Channel2Pin);
 channel_impl!(new_ch3, Ch3, Channel3Pin);
 channel_impl!(new_ch4, Ch4, Channel4Pin);
 
+/// Simple PWM driver.
 pub struct SimplePwm<'d, T> {
     inner: PeripheralRef<'d, T>,
 }
 
 impl<'d, T: CaptureCompare16bitInstance> SimplePwm<'d, T> {
+    /// Create a new simple PWM driver.
     pub fn new(
         tim: impl Peripheral<P = T> + 'd,
         _ch1: Option<PwmPin<'d, T, Ch1>>,
@@ -71,7 +81,7 @@ impl<'d, T: CaptureCompare16bitInstance> SimplePwm<'d, T> {
         let mut this = Self { inner: tim };
 
         this.inner.set_counting_mode(counting_mode);
-        this.set_freq(freq);
+        this.set_frequency(freq);
         this.inner.start();
 
         this.inner.enable_outputs();
@@ -87,15 +97,21 @@ impl<'d, T: CaptureCompare16bitInstance> SimplePwm<'d, T> {
         this
     }
 
+    /// Enable the given channel.
     pub fn enable(&mut self, channel: Channel) {
         self.inner.enable_channel(channel, true);
     }
 
+    /// Disable the given channel.
     pub fn disable(&mut self, channel: Channel) {
         self.inner.enable_channel(channel, false);
     }
 
-    pub fn set_freq(&mut self, freq: Hertz) {
+    /// Set PWM frequency.
+    ///
+    /// Note: when you call this, the max duty value changes, so you will have to
+    /// call `set_duty` on all channels with the duty calculated based on the new max duty.
+    pub fn set_frequency(&mut self, freq: Hertz) {
         let multiplier = if self.inner.get_counting_mode().is_center_aligned() {
             2u8
         } else {
@@ -104,15 +120,22 @@ impl<'d, T: CaptureCompare16bitInstance> SimplePwm<'d, T> {
         self.inner.set_frequency(freq * multiplier);
     }
 
+    /// Get max duty value.
+    ///
+    /// This value depends on the configured frequency and the timer's clock rate from RCC.
     pub fn get_max_duty(&self) -> u16 {
         self.inner.get_max_compare_value() + 1
     }
 
+    /// Set the duty for a given channel.
+    ///
+    /// The value ranges from 0 for 0% duty, to [`get_max_duty`](Self::get_max_duty) for 100% duty, both included.
     pub fn set_duty(&mut self, channel: Channel, duty: u16) {
         assert!(duty <= self.get_max_duty());
         self.inner.set_compare_value(channel, duty)
     }
 
+    /// Set the output polarity for a given channel.
     pub fn set_polarity(&mut self, channel: Channel, polarity: OutputPolarity) {
         self.inner.set_output_polarity(channel, polarity);
     }

embassy-stm32/src/traits.rs

@@ -1,18 +1,18 @@
 #![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))]
+            #[doc = concat!("Get the AF number needed to use this pin as ", stringify!($signal))]
             fn af_num(&self) -> u8;
         }
     };
 }
 
 macro_rules! pin_trait_impl {
-    (crate::$mod:ident::$trait:ident, $instance:ident, $pin:ident, $af:expr) => {
+    (crate::$mod:ident::$trait:ident$(<$mode:ident>)?, $instance:ident, $pin:ident, $af:expr) => {
-        impl crate::$mod::$trait<crate::peripherals::$instance> for crate::peripherals::$pin {
+        impl crate::$mod::$trait<crate::peripherals::$instance $(, crate::$mod::$mode)?> for crate::peripherals::$pin {
             fn af_num(&self) -> u8 {
                 $af
             }
@@ -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) => {
+    (crate::$mod:ident::$trait:ident$(<$mode:ident>)?, $instance:ident, {dmamux: $dmamux:ident}, $request:expr) => {
-        impl<T> crate::$mod::$trait<crate::peripherals::$instance> for T
+        impl<T> crate::$mod::$trait<crate::peripherals::$instance $(, crate::$mod::$mode)?> for T
         where
             T: crate::dma::Channel + crate::dma::MuxChannel<Mux = crate::dma::$dmamux>,
         {
@@ -49,8 +49,8 @@ macro_rules! dma_trait_impl {
     };
 
     // DMAMUX
-    (crate::$mod:ident::$trait:ident, $instance:ident, {dma: $dma:ident}, $request:expr) => {
+    (crate::$mod:ident::$trait:ident$(<$mode:ident>)?, $instance:ident, {dma: $dma:ident}, $request:expr) => {
-        impl<T> crate::$mod::$trait<crate::peripherals::$instance> for T
+        impl<T> crate::$mod::$trait<crate::peripherals::$instance $(, crate::$mod::$mode)?> for T
         where
             T: crate::dma::Channel,
         {
@@ -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) => {
+    (crate::$mod:ident::$trait:ident$(<$mode:ident>)?, $instance:ident, {channel: $channel:ident}, $request:expr) => {
-        impl crate::$mod::$trait<crate::peripherals::$instance> for crate::peripherals::$channel {
+        impl crate::$mod::$trait<crate::peripherals::$instance $(, crate::$mod::$mode)?> for crate::peripherals::$channel {
             fn request(&self) -> crate::dma::Request {
                 $request
             }

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/buffered.rs

@@ -82,6 +82,7 @@ impl<T: BasicInstance> interrupt::typelevel::Handler<T::Interrupt> for Interrupt
     }
 }
 
+/// Buffered UART State
 pub struct State {
     rx_waker: AtomicWaker,
     rx_buf: RingBuffer,
@@ -91,6 +92,7 @@ pub struct State {
 }
 
 impl State {
+    /// Create new state
     pub const fn new() -> Self {
         Self {
             rx_buf: RingBuffer::new(),
@@ -101,15 +103,18 @@ impl State {
     }
 }
 
+/// Bidirectional buffered UART
 pub struct BufferedUart<'d, T: BasicInstance> {
     rx: BufferedUartRx<'d, T>,
     tx: BufferedUartTx<'d, T>,
 }
 
+/// Tx-only buffered UART
 pub struct BufferedUartTx<'d, T: BasicInstance> {
     phantom: PhantomData<&'d mut T>,
 }
 
+/// Rx-only buffered UART
 pub struct BufferedUartRx<'d, T: BasicInstance> {
     phantom: PhantomData<&'d mut T>,
 }
@@ -142,6 +147,7 @@ impl<'d, T: BasicInstance> SetConfig for BufferedUartTx<'d, T> {
 }
 
 impl<'d, T: BasicInstance> BufferedUart<'d, T> {
+    /// Create a new bidirectional buffered UART driver
     pub fn new(
         peri: impl Peripheral<P = T> + 'd,
         _irq: impl interrupt::typelevel::Binding<T::Interrupt, InterruptHandler<T>> + 'd,
@@ -158,6 +164,7 @@ impl<'d, T: BasicInstance> BufferedUart<'d, T> {
         Self::new_inner(peri, rx, tx, tx_buffer, rx_buffer, config)
     }
 
+    /// Create a new bidirectional buffered UART driver with request-to-send and clear-to-send pins
     pub fn new_with_rtscts(
         peri: impl Peripheral<P = T> + 'd,
         _irq: impl interrupt::typelevel::Binding<T::Interrupt, InterruptHandler<T>> + 'd,
@@ -185,6 +192,7 @@ impl<'d, T: BasicInstance> BufferedUart<'d, T> {
         Self::new_inner(peri, rx, tx, tx_buffer, rx_buffer, config)
     }
 
+    /// Create a new bidirectional buffered UART driver with a driver-enable pin
     #[cfg(not(any(usart_v1, usart_v2)))]
     pub fn new_with_de(
         peri: impl Peripheral<P = T> + 'd,
@@ -246,10 +254,12 @@ impl<'d, T: BasicInstance> BufferedUart<'d, T> {
         })
     }
 
+    /// Split the driver into a Tx and Rx part (useful for sending to separate tasks)
     pub fn split(self) -> (BufferedUartTx<'d, T>, BufferedUartRx<'d, T>) {
         (self.tx, self.rx)
     }
 
+    /// Reconfigure the driver
     pub fn set_config(&mut self, config: &Config) -> Result<(), ConfigError> {
         reconfigure::<T>(config)?;
 
@@ -337,6 +347,7 @@ impl<'d, T: BasicInstance> BufferedUartRx<'d, T> {
         }
     }
 
+    /// Reconfigure the driver
     pub fn set_config(&mut self, config: &Config) -> Result<(), ConfigError> {
         reconfigure::<T>(config)?;
 
@@ -418,6 +429,7 @@ impl<'d, T: BasicInstance> BufferedUartTx<'d, T> {
         }
     }
 
+    /// Reconfigure the driver
     pub fn set_config(&mut self, config: &Config) -> Result<(), ConfigError> {
         reconfigure::<T>(config)?;
 

embassy-stm32/src/usart/mod.rs

@@ -1,4 +1,6 @@
+//! Universal Synchronous/Asynchronous Receiver Transmitter (USART, UART, LPUART)
 #![macro_use]
+#![warn(missing_docs)]
 
 use core::future::poll_fn;
 use core::marker::PhantomData;
@@ -76,21 +78,29 @@ impl<T: BasicInstance> interrupt::typelevel::Handler<T::Interrupt> for Interrupt
 
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
+/// Number of data bits
 pub enum DataBits {
+    /// 8 Data Bits
     DataBits8,
+    /// 9 Data Bits
     DataBits9,
 }
 
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
+/// Parity
 pub enum Parity {
+    /// No parity
     ParityNone,
+    /// Even Parity
     ParityEven,
+    /// Odd Parity
     ParityOdd,
 }
 
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
+/// Number of stop bits
 pub enum StopBits {
     #[doc = "1 stop bit"]
     STOP1,
@@ -105,26 +115,37 @@ pub enum StopBits {
 #[non_exhaustive]
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
+/// Config Error
 pub enum ConfigError {
+    /// Baudrate too low
     BaudrateTooLow,
+    /// Baudrate too high
     BaudrateTooHigh,
+    /// Rx or Tx not enabled
     RxOrTxNotEnabled,
 }
 
 #[non_exhaustive]
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
+/// Config
 pub struct Config {
+    /// Baud rate
     pub baudrate: u32,
+    /// Number of data bits
     pub data_bits: DataBits,
+    /// Number of stop bits
     pub stop_bits: StopBits,
+    /// Parity type
     pub parity: Parity,
-    /// if true, on read-like method, if there is a latent error pending,
+
-    /// read will abort, the error reported and cleared
+    /// If true: on a read-like method, if there is a latent error pending,
-    /// if false, the error is ignored and cleared
+    /// the read will abort and the error will be reported and cleared
+    ///
+    /// If false: the error is ignored and cleared
     pub detect_previous_overrun: bool,
 
     /// Set this to true if the line is considered noise free.
-    /// This will increase the receivers tolerance to clock deviations,
+    /// This will increase the receiver’s tolerance to clock deviations,
     /// but will effectively disable noise detection.
     #[cfg(not(usart_v1))]
     pub assume_noise_free: bool,
@@ -187,6 +208,7 @@ enum ReadCompletionEvent {
     Idle(usize),
 }
 
+/// Bidirectional UART Driver
 pub struct Uart<'d, T: BasicInstance, TxDma = NoDma, RxDma = NoDma> {
     tx: UartTx<'d, T, TxDma>,
     rx: UartRx<'d, T, RxDma>,
@@ -202,6 +224,7 @@ impl<'d, T: BasicInstance, TxDma, RxDma> SetConfig for Uart<'d, T, TxDma, RxDma>
     }
 }
 
+/// Tx-only UART Driver
 pub struct UartTx<'d, T: BasicInstance, TxDma = NoDma> {
     phantom: PhantomData<&'d mut T>,
     tx_dma: PeripheralRef<'d, TxDma>,
@@ -216,6 +239,7 @@ impl<'d, T: BasicInstance, TxDma> SetConfig for UartTx<'d, T, TxDma> {
     }
 }
 
+/// Rx-only UART Driver
 pub struct UartRx<'d, T: BasicInstance, RxDma = NoDma> {
     _peri: PeripheralRef<'d, T>,
     rx_dma: PeripheralRef<'d, RxDma>,
@@ -246,6 +270,7 @@ impl<'d, T: BasicInstance, TxDma> UartTx<'d, T, TxDma> {
         Self::new_inner(peri, tx, tx_dma, config)
     }
 
+    /// Create a new tx-only UART with a clear-to-send pin
     pub fn new_with_cts(
         peri: impl Peripheral<P = T> + 'd,
         tx: impl Peripheral<P = impl TxPin<T>> + 'd,
@@ -287,10 +312,12 @@ impl<'d, T: BasicInstance, TxDma> UartTx<'d, T, TxDma> {
         })
     }
 
+    /// Reconfigure the driver
     pub fn set_config(&mut self, config: &Config) -> Result<(), ConfigError> {
         reconfigure::<T>(config)
     }
 
+    /// Initiate an asynchronous UART write
     pub async fn write(&mut self, buffer: &[u8]) -> Result<(), Error>
     where
         TxDma: crate::usart::TxDma<T>,
@@ -307,6 +334,7 @@ impl<'d, T: BasicInstance, TxDma> UartTx<'d, T, TxDma> {
         Ok(())
     }
 
+    /// Perform a blocking UART write
     pub fn blocking_write(&mut self, buffer: &[u8]) -> Result<(), Error> {
         let r = T::regs();
         for &b in buffer {
@@ -316,6 +344,7 @@ impl<'d, T: BasicInstance, TxDma> UartTx<'d, T, TxDma> {
         Ok(())
     }
 
+    /// Block until transmission complete
     pub fn blocking_flush(&mut self) -> Result<(), Error> {
         let r = T::regs();
         while !sr(r).read().tc() {}
@@ -337,6 +366,7 @@ impl<'d, T: BasicInstance, RxDma> UartRx<'d, T, RxDma> {
         Self::new_inner(peri, rx, rx_dma, config)
     }
 
+    /// Create a new rx-only UART with a request-to-send pin
     pub fn new_with_rts(
         peri: impl Peripheral<P = T> + 'd,
         _irq: impl interrupt::typelevel::Binding<T::Interrupt, InterruptHandler<T>> + 'd,
@@ -386,6 +416,7 @@ impl<'d, T: BasicInstance, RxDma> UartRx<'d, T, RxDma> {
         })
     }
 
+    /// Reconfigure the driver
     pub fn set_config(&mut self, config: &Config) -> Result<(), ConfigError> {
         reconfigure::<T>(config)
     }
@@ -443,6 +474,7 @@ impl<'d, T: BasicInstance, RxDma> UartRx<'d, T, RxDma> {
         Ok(sr.rxne())
     }
 
+    /// Initiate an asynchronous UART read
     pub async fn read(&mut self, buffer: &mut [u8]) -> Result<(), Error>
     where
         RxDma: crate::usart::RxDma<T>,
@@ -452,6 +484,7 @@ impl<'d, T: BasicInstance, RxDma> UartRx<'d, T, RxDma> {
         Ok(())
     }
 
+    /// Read a single u8 if there is one available, otherwise return WouldBlock
     pub fn nb_read(&mut self) -> Result<u8, nb::Error<Error>> {
         let r = T::regs();
         if self.check_rx_flags()? {
@@ -461,6 +494,7 @@ impl<'d, T: BasicInstance, RxDma> UartRx<'d, T, RxDma> {
         }
     }
 
+    /// Perform a blocking read into `buffer`
     pub fn blocking_read(&mut self, buffer: &mut [u8]) -> Result<(), Error> {
         let r = T::regs();
         for b in buffer {
@@ -470,6 +504,7 @@ impl<'d, T: BasicInstance, RxDma> UartRx<'d, T, RxDma> {
         Ok(())
     }
 
+    /// Initiate an asynchronous read with idle line detection enabled
     pub async fn read_until_idle(&mut self, buffer: &mut [u8]) -> Result<usize, Error>
     where
         RxDma: crate::usart::RxDma<T>,
@@ -694,6 +729,7 @@ impl<'d, T: BasicInstance, TxDma> Drop for UartRx<'d, T, TxDma> {
 }
 
 impl<'d, T: BasicInstance, TxDma, RxDma> Uart<'d, T, TxDma, RxDma> {
+    /// Create a new bidirectional UART
     pub fn new(
         peri: impl Peripheral<P = T> + 'd,
         rx: impl Peripheral<P = impl RxPin<T>> + 'd,
@@ -710,6 +746,7 @@ impl<'d, T: BasicInstance, TxDma, RxDma> Uart<'d, T, TxDma, RxDma> {
         Self::new_inner(peri, rx, tx, tx_dma, rx_dma, config)
     }
 
+    /// Create a new bidirectional UART with request-to-send and clear-to-send pins
     pub fn new_with_rtscts(
         peri: impl Peripheral<P = T> + 'd,
         rx: impl Peripheral<P = impl RxPin<T>> + 'd,
@@ -737,6 +774,7 @@ impl<'d, T: BasicInstance, TxDma, RxDma> Uart<'d, T, TxDma, RxDma> {
     }
 
     #[cfg(not(any(usart_v1, usart_v2)))]
+    /// Create a new bidirectional UART with a driver-enable pin
     pub fn new_with_de(
         peri: impl Peripheral<P = T> + 'd,
         rx: impl Peripheral<P = impl RxPin<T>> + 'd,
@@ -812,6 +850,7 @@ impl<'d, T: BasicInstance, TxDma, RxDma> Uart<'d, T, TxDma, RxDma> {
         })
     }
 
+    /// Initiate an asynchronous write
     pub async fn write(&mut self, buffer: &[u8]) -> Result<(), Error>
     where
         TxDma: crate::usart::TxDma<T>,
@@ -819,14 +858,17 @@ impl<'d, T: BasicInstance, TxDma, RxDma> Uart<'d, T, TxDma, RxDma> {
         self.tx.write(buffer).await
     }
 
+    /// Perform a blocking write
     pub fn blocking_write(&mut self, buffer: &[u8]) -> Result<(), Error> {
         self.tx.blocking_write(buffer)
     }
 
+    /// Block until transmission complete
     pub fn blocking_flush(&mut self) -> Result<(), Error> {
         self.tx.blocking_flush()
     }
 
+    /// Initiate an asynchronous read into `buffer`
     pub async fn read(&mut self, buffer: &mut [u8]) -> Result<(), Error>
     where
         RxDma: crate::usart::RxDma<T>,
@@ -834,14 +876,17 @@ impl<'d, T: BasicInstance, TxDma, RxDma> Uart<'d, T, TxDma, RxDma> {
         self.rx.read(buffer).await
     }
 
+    /// Read a single `u8` or return `WouldBlock`
     pub fn nb_read(&mut self) -> Result<u8, nb::Error<Error>> {
         self.rx.nb_read()
     }
 
+    /// Perform a blocking read into `buffer`
     pub fn blocking_read(&mut self, buffer: &mut [u8]) -> Result<(), Error> {
         self.rx.blocking_read(buffer)
     }
 
+    /// Initiate an an asynchronous read with idle line detection enabled
     pub async fn read_until_idle(&mut self, buffer: &mut [u8]) -> Result<usize, Error>
     where
         RxDma: crate::usart::RxDma<T>,
@@ -1291,8 +1336,10 @@ pub(crate) mod sealed {
     }
 }
 
+/// Basic UART driver instance
 pub trait BasicInstance: Peripheral<P = Self> + sealed::BasicInstance + 'static + Send {}
 
+/// Full UART driver instance
 pub trait FullInstance: sealed::FullInstance {}
 
 pin_trait!(RxPin, BasicInstance);

embassy-stm32/src/usart/ringbuffered.rs

@@ -11,6 +11,7 @@ use super::{clear_interrupt_flags, rdr, reconfigure, sr, BasicInstance, Config,
 use crate::dma::ReadableRingBuffer;
 use crate::usart::{Regs, Sr};
 
+/// Rx-only Ring-buffered UART Driver
 pub struct RingBufferedUartRx<'d, T: BasicInstance, RxDma: super::RxDma<T>> {
     _peri: PeripheralRef<'d, T>,
     ring_buf: ReadableRingBuffer<'d, RxDma, u8>,
@@ -27,8 +28,8 @@ impl<'d, T: BasicInstance, RxDma: super::RxDma<T>> SetConfig for RingBufferedUar
 
 impl<'d, T: BasicInstance, RxDma: super::RxDma<T>> UartRx<'d, T, RxDma> {
     /// Turn the `UartRx` into a buffered uart which can continously receive in the background
-    /// without the possibility of loosing bytes. The `dma_buf` is a buffer registered to the
+    /// without the possibility of losing bytes. The `dma_buf` is a buffer registered to the
-    /// DMA controller, and must be sufficiently large, such that it will not overflow.
+    /// DMA controller, and must be large enough to prevent overflows.
     pub fn into_ring_buffered(self, dma_buf: &'d mut [u8]) -> RingBufferedUartRx<'d, T, RxDma> {
         assert!(!dma_buf.is_empty() && dma_buf.len() <= 0xFFFF);
 
@@ -49,6 +50,7 @@ impl<'d, T: BasicInstance, RxDma: super::RxDma<T>> UartRx<'d, T, RxDma> {
 }
 
 impl<'d, T: BasicInstance, RxDma: super::RxDma<T>> RingBufferedUartRx<'d, T, RxDma> {
+    /// Clear the ring buffer and start receiving in the background
     pub fn start(&mut self) -> Result<(), Error> {
         // Clear the ring buffer so that it is ready to receive data
         self.ring_buf.clear();
@@ -64,6 +66,7 @@ impl<'d, T: BasicInstance, RxDma: super::RxDma<T>> RingBufferedUartRx<'d, T, RxD
         Err(err)
     }
 
+    /// Cleanly stop and reconfigure the driver
     pub fn set_config(&mut self, config: &Config) -> Result<(), ConfigError> {
         self.teardown_uart();
         reconfigure::<T>(config)

embassy-stm32/src/usb/mod.rs

@@ -1,3 +1,5 @@
+//! Universal Serial Bus (USB)
+
 use crate::interrupt;
 use crate::rcc::RccPeripheral;
 
@@ -10,7 +12,9 @@ pub(crate) mod sealed {
     }
 }
 
+/// USB instance trait.
 pub trait Instance: sealed::Instance + RccPeripheral + 'static {
+    /// Interrupt for this USB instance.
     type Interrupt: interrupt::typelevel::Interrupt;
 }
 

embassy-stm32/src/usb/usb.rs

@@ -244,6 +244,7 @@ struct EndpointData {
     used_out: bool,
 }
 
+/// USB driver.
 pub struct Driver<'d, T: Instance> {
     phantom: PhantomData<&'d mut T>,
     alloc: [EndpointData; EP_COUNT],
@@ -251,6 +252,7 @@ pub struct Driver<'d, T: Instance> {
 }
 
 impl<'d, T: Instance> Driver<'d, T> {
+    /// Create a new USB driver.
     pub fn new(
         _usb: impl Peripheral<P = T> + 'd,
         _irq: impl interrupt::typelevel::Binding<T::Interrupt, InterruptHandler<T>> + 'd,
@@ -465,6 +467,7 @@ impl<'d, T: Instance> driver::Driver<'d> for Driver<'d, T> {
     }
 }
 
+/// USB bus.
 pub struct Bus<'d, T: Instance> {
     phantom: PhantomData<&'d mut T>,
     ep_types: [EpType; EP_COUNT - 1],
@@ -640,6 +643,7 @@ trait Dir {
     fn waker(i: usize) -> &'static AtomicWaker;
 }
 
+/// Marker type for the "IN" direction.
 pub enum In {}
 impl Dir for In {
     fn dir() -> Direction {
@@ -652,6 +656,7 @@ impl Dir for In {
     }
 }
 
+/// Marker type for the "OUT" direction.
 pub enum Out {}
 impl Dir for Out {
     fn dir() -> Direction {
@@ -664,6 +669,7 @@ impl Dir for Out {
     }
 }
 
+/// USB endpoint.
 pub struct Endpoint<'d, T: Instance, D> {
     _phantom: PhantomData<(&'d mut T, D)>,
     info: EndpointInfo,
@@ -813,6 +819,7 @@ impl<'d, T: Instance> driver::EndpointIn for Endpoint<'d, T, In> {
     }
 }
 
+/// USB control pipe.
 pub struct ControlPipe<'d, T: Instance> {
     _phantom: PhantomData<&'d mut T>,
     max_packet_size: u16,

embassy-stm32/src/usb_otg/mod.rs

@@ -1,3 +1,5 @@
+//! USB On The Go (OTG)
+
 use crate::rcc::RccPeripheral;
 use crate::{interrupt, peripherals};
 
@@ -18,7 +20,9 @@ pub(crate) mod sealed {
     }
 }
 
+/// USB OTG instance.
 pub trait Instance: sealed::Instance + RccPeripheral {
+    /// Interrupt for this USB OTG instance.
     type Interrupt: interrupt::typelevel::Interrupt;
 }
 

embassy-stm32/src/usb_otg/usb.rs

@@ -204,6 +204,7 @@ pub enum PhyType {
 }
 
 impl PhyType {
+    /// Get whether this PHY is any of the internal types.
     pub fn internal(&self) -> bool {
         match self {
             PhyType::InternalFullSpeed | PhyType::InternalHighSpeed => true,
@@ -211,6 +212,7 @@ impl PhyType {
         }
     }
 
+    /// Get whether this PHY is any of the high-speed types.
     pub fn high_speed(&self) -> bool {
         match self {
             PhyType::InternalFullSpeed => false,
@@ -218,7 +220,7 @@ impl PhyType {
         }
     }
 
-    pub fn to_dspd(&self) -> vals::Dspd {
+    fn to_dspd(&self) -> vals::Dspd {
         match self {
             PhyType::InternalFullSpeed => vals::Dspd::FULL_SPEED_INTERNAL,
             PhyType::InternalHighSpeed => vals::Dspd::HIGH_SPEED,
@@ -230,6 +232,7 @@ impl PhyType {
 /// Indicates that [State::ep_out_buffers] is empty.
 const EP_OUT_BUFFER_EMPTY: u16 = u16::MAX;
 
+/// USB OTG driver state.
 pub struct State<const EP_COUNT: usize> {
     /// Holds received SETUP packets. Available if [State::ep0_setup_ready] is true.
     ep0_setup_data: UnsafeCell<[u8; 8]>,
@@ -247,6 +250,7 @@ unsafe impl<const EP_COUNT: usize> Send for State<EP_COUNT> {}
 unsafe impl<const EP_COUNT: usize> Sync for State<EP_COUNT> {}
 
 impl<const EP_COUNT: usize> State<EP_COUNT> {
+    /// Create a new State.
     pub const fn new() -> Self {
         const NEW_AW: AtomicWaker = AtomicWaker::new();
         const NEW_BUF: UnsafeCell<*mut u8> = UnsafeCell::new(0 as _);
@@ -271,6 +275,7 @@ struct EndpointData {
     fifo_size_words: u16,
 }
 
+/// USB driver config.
 #[non_exhaustive]
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub struct Config {
@@ -297,6 +302,7 @@ impl Default for Config {
     }
 }
 
+/// USB driver.
 pub struct Driver<'d, T: Instance> {
     config: Config,
     phantom: PhantomData<&'d mut T>,
@@ -527,6 +533,7 @@ impl<'d, T: Instance> embassy_usb_driver::Driver<'d> for Driver<'d, T> {
     }
 }
 
+/// USB bus.
 pub struct Bus<'d, T: Instance> {
     config: Config,
     phantom: PhantomData<&'d mut T>,
@@ -1092,6 +1099,7 @@ trait Dir {
     fn dir() -> Direction;
 }
 
+/// Marker type for the "IN" direction.
 pub enum In {}
 impl Dir for In {
     fn dir() -> Direction {
@@ -1099,6 +1107,7 @@ impl Dir for In {
     }
 }
 
+/// Marker type for the "OUT" direction.
 pub enum Out {}
 impl Dir for Out {
     fn dir() -> Direction {
@@ -1106,6 +1115,7 @@ impl Dir for Out {
     }
 }
 
+/// USB endpoint.
 pub struct Endpoint<'d, T: Instance, D> {
     _phantom: PhantomData<(&'d mut T, D)>,
     info: EndpointInfo,
@@ -1299,6 +1309,7 @@ impl<'d, T: Instance> embassy_usb_driver::EndpointIn for Endpoint<'d, T, In> {
     }
 }
 
+/// USB control pipe.
 pub struct ControlPipe<'d, T: Instance> {
     _phantom: PhantomData<&'d mut T>,
     max_packet_size: u16,

embassy-stm32/src/wdg/mod.rs

@@ -1,3 +1,4 @@
+//! Watchdog Timer (IWDG, WWDG)
 use core::marker::PhantomData;
 
 use embassy_hal_internal::{into_ref, Peripheral};
@@ -5,6 +6,7 @@ use stm32_metapac::iwdg::vals::{Key, Pr};
 
 use crate::rcc::LSI_FREQ;
 
+/// Independent watchdog (IWDG) driver.
 pub struct IndependentWatchdog<'d, T: Instance> {
     wdg: PhantomData<&'d mut T>,
 }
@@ -63,10 +65,12 @@ impl<'d, T: Instance> IndependentWatchdog<'d, T> {
         IndependentWatchdog { wdg: PhantomData }
     }
 
+    /// Unleash (start) the watchdog.
     pub fn unleash(&mut self) {
         T::regs().kr().write(|w| w.set_key(Key::START));
     }
 
+    /// Pet (reload, refresh) the watchdog.
     pub fn pet(&mut self) {
         T::regs().kr().write(|w| w.set_key(Key::RESET));
     }
@@ -78,6 +82,7 @@ mod sealed {
     }
 }
 
+/// IWDG instance trait.
 pub trait Instance: sealed::Instance {}
 
 foreach_peripheral!(

embassy-sync/src/signal.rs

@@ -111,6 +111,20 @@ where
         poll_fn(move |cx| self.poll_wait(cx))
     }
 
+    /// non-blocking method to try and take the signal value.
+    pub fn try_take(&self) -> Option<T> {
+        self.state.lock(|cell| {
+            let state = cell.replace(State::None);
+            match state {
+                State::Signaled(res) => Some(res),
+                state => {
+                    cell.set(state);
+                    None
+                }
+            }
+        })
+    }
+
     /// non-blocking method to check whether this signal has been signaled.
     pub fn signaled(&self) -> bool {
         self.state.lock(|cell| {

embassy-usb-dfu/README.md

@@ -0,0 +1,20 @@
+# embassy-usb-dfu
+
+An implementation of the USB DFU 1.1 protocol using embassy-boot. It has 2 components depending on which feature is enabled by the user.
+
+* DFU protocol mode, enabled by the `dfu` feature. This mode corresponds to the transfer phase DFU protocol described by the USB IF. It supports DFU_DNLOAD requests if marked by the user, and will automatically reset the chip once a DFU transaction has been completed. It also responds to DFU_GETSTATUS, DFU_GETSTATE, DFU_ABORT, and DFU_CLRSTATUS with no user intervention.
+* DFU runtime mode, enabled by the `application feature`. This mode allows users to expose a DFU interface on their USB device, informing the host of the capability to DFU over USB, and allowing the host to reset the device into its bootloader to complete a DFU operation. Supports DFU_GETSTATUS and DFU_DETACH. When detach/reset is seen by the device as described by the standard, will write a new DFU magic number into the bootloader state in flash, and reset the system.
+
+## 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.