docs: document usb-logger and usb-dfu

docs: document public apis for cyw43 driver

embassy-boot/boot/Cargo.toml

@@ -26,22 +26,25 @@ features = ["defmt"]
 defmt = { version = "0.3", optional = true }
 digest = "0.10"
 log = { version = "0.4", optional = true }
-ed25519-dalek = { version = "2", default_features = false, features = ["digest"], optional = true }
+ed25519-dalek = { version = "1.0.1", default_features = false, features = ["u32_backend"], 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 = { version = "0.3", optional = true }
+salty = { git = "https://github.com/ycrypto/salty.git", rev = "a9f17911a5024698406b75c0fac56ab5ccf6a8c7", optional = true }
-signature = { version = "2.0", default-features = false }
+signature = { version = "1.6.4", default-features = false }
 
 [dev-dependencies]
 log = "0.4"
 env_logger = "0.9"
-rand = "0.8"
+rand = "0.7" # ed25519-dalek v1.0.1 depends on this exact version
 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;
+use ed25519_dalek::Digest as _;
 
 pub struct Sha512(ed25519_dalek::Sha512);
 
@@ -12,7 +12,7 @@ impl Default for Sha512 {
 
 impl Update for Sha512 {
     fn update(&mut self, data: &[u8]) {
-        Digest::update(&mut self.0, data)
+        self.0.update(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; 32],
+        _public_key: &[u8],
-        _signature: &[u8; 64],
+        _signature: &[u8],
         _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::{Signature, SignatureError, Verifier, VerifyingKey};
+            use ed25519_dalek::{PublicKey, Signature, SignatureError, Verifier};
 
             use crate::digest_adapters::ed25519_dalek::Sha512;
 
             let into_signature_error = |e: SignatureError| FirmwareUpdaterError::Signature(e.into());
 
-            let public_key = VerifyingKey::from_bytes(_public_key).map_err(into_signature_error)?;
+            let public_key = PublicKey::from_bytes(_public_key).map_err(into_signature_error)?;
-            let signature = Signature::from_bytes(_signature);
+            let signature = Signature::from_bytes(_signature).map_err(into_signature_error)?;
 
             let mut chunk_buf = [0; 2];
             let mut message = [0; 64];
@@ -106,6 +106,7 @@ 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;
@@ -114,8 +115,10 @@ impl<'d, DFU: NorFlash, STATE: NorFlash> FirmwareUpdater<'d, DFU, STATE> {
                 FirmwareUpdaterError::Signature(signature::Error::default())
             }
 
-            let public_key = PublicKey::try_from(_public_key).map_err(into_signature_error)?;
+            let public_key: [u8; PUBLICKEY_SERIALIZED_LENGTH] = _public_key.try_into().map_err(into_signature_error)?;
-            let signature = Signature::try_from(_signature).map_err(into_signature_error)?;
+            let public_key = PublicKey::try_from(&public_key).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; 32],
+        _public_key: &[u8],
-        _signature: &[u8; 64],
+        _signature: &[u8],
         _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::{Signature, SignatureError, Verifier, VerifyingKey};
+            use ed25519_dalek::{PublicKey, Signature, SignatureError, Verifier};
 
             use crate::digest_adapters::ed25519_dalek::Sha512;
 
             let into_signature_error = |e: SignatureError| FirmwareUpdaterError::Signature(e.into());
 
-            let public_key = VerifyingKey::from_bytes(_public_key).map_err(into_signature_error)?;
+            let public_key = PublicKey::from_bytes(_public_key).map_err(into_signature_error)?;
-            let signature = Signature::from_bytes(_signature);
+            let signature = Signature::from_bytes(_signature).map_err(into_signature_error)?;
 
             let mut message = [0; 64];
             let mut chunk_buf = [0; 2];
@@ -113,6 +113,7 @@ 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;
@@ -121,8 +122,10 @@ impl<'d, DFU: NorFlash, STATE: NorFlash> BlockingFirmwareUpdater<'d, DFU, STATE>
                 FirmwareUpdaterError::Signature(signature::Error::default())
             }
 
-            let public_key = PublicKey::try_from(_public_key).map_err(into_signature_error)?;
+            let public_key: [u8; PUBLICKEY_SERIALIZED_LENGTH] = _public_key.try_into().map_err(into_signature_error)?;
-            let signature = Signature::try_from(_signature).map_err(into_signature_error)?;
+            let public_key = PublicKey::try_from(&public_key).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,19 +275,21 @@ mod tests {
         // The following key setup is based on:
         // https://docs.rs/ed25519-dalek/latest/ed25519_dalek/#example
 
-        use ed25519_dalek::{Digest, Sha512, Signature, Signer, SigningKey, VerifyingKey};
+        use ed25519_dalek::Keypair;
         use rand::rngs::OsRng;
 
         let mut csprng = OsRng {};
-        let keypair = SigningKey::generate(&mut csprng);
+        let keypair: Keypair = Keypair::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);
 
-        let public_key = keypair.verifying_key();
+        use ed25519_dalek::PublicKey;
+        let public_key: PublicKey = keypair.public;
 
         // Setup flash
         let flash = BlockingTestFlash::new(BootLoaderConfig {

embassy-stm32/Cargo.toml

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

embassy-stm32/src/dma/bdma.rs

@@ -303,14 +303,20 @@ impl<'a, C: Channel> Transfer<'a, C> {
         ch.cr().write(|w| {
             w.set_psize(data_size.into());
             w.set_msize(data_size.into());
-            w.set_minc(incr_mem);
+            if 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);
@@ -346,7 +352,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();
+        let circular = ch.cr().read().circ() == vals::Circ::ENABLED;
         let tcif = STATE.complete_count[self.channel.index()].load(Ordering::Acquire) != 0;
         en && (circular || !tcif)
     }
@@ -461,12 +467,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(true);
+        w.set_minc(vals::Inc::ENABLED);
         w.set_dir(dir.into());
         w.set_teie(true);
         w.set_htie(true);
         w.set_tcie(true);
-        w.set_circ(true);
+        w.set_circ(vals::Circ::ENABLED);
         w.set_pl(vals::Pl::VERYHIGH);
         w.set_en(true);
 
@@ -619,12 +625,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(true);
+        w.set_minc(vals::Inc::ENABLED);
         w.set_dir(dir.into());
         w.set_teie(true);
         w.set_htie(true);
         w.set_tcie(true);
-        w.set_circ(true);
+        w.set_circ(vals::Circ::ENABLED);
         w.set_pl(vals::Pl::VERYHIGH);
         w.set_en(true);
 

embassy-stm32/src/dma/dma.rs

@@ -382,13 +382,18 @@ 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(incr_mem);
+            w.set_minc(match incr_mem {
-            w.set_pinc(false);
+                true => vals::Inc::INCREMENTED,
+                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);
@@ -540,8 +545,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(true);
+            w.set_minc(vals::Inc::INCREMENTED);
-            w.set_pinc(false);
+            w.set_pinc(vals::Inc::FIXED);
             w.set_teie(true);
             w.set_tcie(true);
             #[cfg(dma_v1)]
@@ -698,12 +703,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(true);
+        w.set_minc(vals::Inc::INCREMENTED);
-        w.set_pinc(false);
+        w.set_pinc(vals::Inc::FIXED);
         w.set_teie(true);
         w.set_htie(options.half_transfer_ir);
         w.set_tcie(true);
-        w.set_circ(true);
+        w.set_circ(vals::Circ::ENABLED);
         #[cfg(dma_v1)]
         w.set_trbuff(true);
         #[cfg(dma_v2)]
@@ -873,12 +878,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(true);
+        w.set_minc(vals::Inc::INCREMENTED);
-        w.set_pinc(false);
+        w.set_pinc(vals::Inc::FIXED);
         w.set_teie(true);
         w.set_htie(options.half_transfer_ir);
         w.set_tcie(true);
-        w.set_circ(true);
+        w.set_circ(vals::Circ::ENABLED);
         #[cfg(dma_v1)]
         w.set_trbuff(true);
         #[cfg(dma_v2)]

embassy-stm32/src/dma/gpdma.rs

@@ -16,7 +16,6 @@ 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]
@@ -114,13 +113,10 @@ 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 {}
 
@@ -135,14 +131,12 @@ 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,
@@ -153,7 +147,6 @@ 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,
@@ -179,7 +172,6 @@ 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,
@@ -190,7 +182,6 @@ 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,
@@ -216,7 +207,6 @@ 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,
@@ -307,9 +297,6 @@ 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| {
@@ -317,10 +304,6 @@ 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();
@@ -334,7 +317,6 @@ 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/hrtim/mod.rs

@@ -15,42 +15,38 @@ use crate::rcc::get_freqs;
 use crate::time::Hertz;
 use crate::Peripheral;
 
-/// HRTIM burst controller instance.
+pub enum Source {
+    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>,
@@ -64,26 +60,22 @@ mod sealed {
     }
 }
 
-/// Advanced channel instance trait.
 pub trait AdvancedChannel<T: Instance>: sealed::AdvancedChannel<T> {}
 
-/// HRTIM PWM pin.
+pub struct PwmPin<'d, Perip, Channel> {
-pub struct PwmPin<'d, T, C> {
     _pin: PeripheralRef<'d, AnyPin>,
-    phantom: PhantomData<(T, C)>,
+    phantom: PhantomData<(Perip, Channel)>,
 }
 
-/// HRTIM complementary PWM pin.
+pub struct ComplementaryPwmPin<'d, Perip, Channel> {
-pub struct ComplementaryPwmPin<'d, T, C> {
     _pin: PeripheralRef<'d, AnyPin>,
-    phantom: PhantomData<(T, C)>,
+    phantom: PhantomData<(Perip, Channel)>,
 }
 
 macro_rules! advanced_channel_impl {
     ($new_chx:ident, $channel:tt, $ch_num:expr, $pin_trait:ident, $complementary_pin_trait:ident) => {
-        impl<'d, T: Instance> PwmPin<'d, T, $channel<T>> {
+        impl<'d, Perip: Instance> PwmPin<'d, Perip, $channel<Perip>> {
-            #[doc = concat!("Create a new ", stringify!($channel), " PWM pin instance.")]
+            pub fn $new_chx(pin: impl Peripheral<P = impl $pin_trait<Perip>> + 'd) -> Self {
-            pub fn $new_chx(pin: impl Peripheral<P = impl $pin_trait<T>> + 'd) -> Self {
                 into_ref!(pin);
                 critical_section::with(|_| {
                     pin.set_low();
@@ -98,9 +90,8 @@ macro_rules! advanced_channel_impl {
             }
         }
 
-        impl<'d, T: Instance> ComplementaryPwmPin<'d, T, $channel<T>> {
+        impl<'d, Perip: Instance> ComplementaryPwmPin<'d, Perip, $channel<Perip>> {
-            #[doc = concat!("Create a new ", stringify!($channel), " complementary PWM pin instance.")]
+            pub fn $new_chx(pin: impl Peripheral<P = impl $complementary_pin_trait<Perip>> + 'd) -> Self {
-            pub fn $new_chx(pin: impl Peripheral<P = impl $complementary_pin_trait<T>> + 'd) -> Self {
                 into_ref!(pin);
                 critical_section::with(|_| {
                     pin.set_low();
@@ -135,29 +126,18 @@ 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>>>,
@@ -220,7 +200,13 @@ impl<'d, T: Instance> AdvancedPwm<'d, T> {
     }
 }
 
-/// Fixed-frequency bridge converter driver.
+impl<T: Instance> BurstController<T> {
+    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
@@ -239,7 +225,6 @@ 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};
 
@@ -296,17 +281,14 @@ 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
@@ -319,7 +301,6 @@ 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
@@ -376,7 +357,7 @@ impl<T: Instance, C: AdvancedChannel<T>> BridgeConverter<T, C> {
     }
 }
 
-/// Variable-frequency resonant converter driver.
+/// Represents a variable-frequency resonant converter
 ///
 /// 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
@@ -389,7 +370,6 @@ 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);
 
@@ -428,7 +408,6 @@ 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,6 +125,7 @@ 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();
 
@@ -147,10 +148,13 @@ 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/ipcc.rs

@@ -1,5 +1,3 @@
-//! Inter-Process Communication Controller (IPCC)
-
 use core::future::poll_fn;
 use core::sync::atomic::{compiler_fence, Ordering};
 use core::task::Poll;
@@ -43,7 +41,6 @@ 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 {
@@ -75,7 +72,6 @@ impl interrupt::typelevel::Handler<interrupt::typelevel::IPCC_C1_TX> for Transmi
     }
 }
 
-/// IPCC config.
 #[non_exhaustive]
 #[derive(Clone, Copy, Default)]
 pub struct Config {
@@ -83,8 +79,6 @@ pub struct Config {
     // reserved for future use
 }
 
-/// Channel.
-#[allow(missing_docs)]
 #[derive(Debug, Clone, Copy)]
 #[repr(C)]
 pub enum IpccChannel {
@@ -96,11 +90,9 @@ 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,6 +1,5 @@
 #![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>"#)]
@@ -80,7 +79,6 @@ pub(crate) mod _generated {
     #![allow(dead_code)]
     #![allow(unused_imports)]
     #![allow(non_snake_case)]
-    #![allow(missing_docs)]
 
     include!(concat!(env!("OUT_DIR"), "/_generated.rs"));
 }

embassy-stm32/src/low_power.rs

@@ -1,53 +1,50 @@
-//! Low-power support.
+/// The STM32 line of microcontrollers support various deep-sleep modes which exploit clock-gating
-//!
+/// to reduce power consumption. `embassy-stm32` provides a low-power executor, [`Executor`] which
-//! The STM32 line of microcontrollers support various deep-sleep modes which exploit clock-gating
+/// can use knowledge of which peripherals are currently blocked upon to transparently and safely
-//! to reduce power consumption. `embassy-stm32` provides a low-power executor, [`Executor`] which
+/// enter such low-power modes (currently, only `STOP2`) when idle.
-//! can use knowledge of which peripherals are currently blocked upon to transparently and safely
+///
-//! enter such low-power modes (currently, only `STOP2`) when idle.
+/// 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
-//! The executor determines which peripherals are active by their RCC state; consequently,
+/// exceptions to this rule:
-//! low-power states can only be entered if all peripherals have been `drop`'d. There are a few
+///
-//! exceptions to this rule:
+///  * `GPIO`
-//!
+///  * `RCC`
-//!  * `GPIO`
+///
-//!  * `RCC`
+/// 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
-//! Since entering and leaving low-power modes typically incurs a significant latency, the
+/// [`time_driver::MIN_STOP_PAUSE`] in the future.
-//! low-power executor will only attempt to enter when the next timer event is at least
+///
-//! [`time_driver::MIN_STOP_PAUSE`] in the future.
+/// 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
-//! Currently there is no macro analogous to `embassy_executor::main` for this executor;
+/// of the `RTC` peripheral to the executor. This will typically look like
-//! consequently one must define their entrypoint manually. Moveover, you must relinquish control
+///
-//! of the `RTC` peripheral to the executor. This will typically look like
+/// ```rust,no_run
-//!
+/// use embassy_executor::Spawner;
-//! ```rust,no_run
+/// use embassy_stm32::low_power::Executor;
-//! use embassy_executor::Spawner;
+/// use embassy_stm32::rtc::{Rtc, RtcConfig};
-//! use embassy_stm32::low_power::Executor;
+/// use static_cell::make_static;
-//! use embassy_stm32::rtc::{Rtc, RtcConfig};
+///
-//! use static_cell::make_static;
+/// #[cortex_m_rt::entry]
-//!
+/// fn main() -> ! {
-//! #[cortex_m_rt::entry]
+///     Executor::take().run(|spawner| {
-//! fn main() -> ! {
+///         unwrap!(spawner.spawn(async_main(spawner)));
-//!     Executor::take().run(|spawner| {
+///     });
-//!         unwrap!(spawner.spawn(async_main(spawner)));
+/// }
-//!     });
+///
-//! }
+/// #[embassy_executor::task]
-//!
+/// async fn async_main(spawner: Spawner) {
-//! #[embassy_executor::task]
+///     // initialize the platform...
-//! async fn async_main(spawner: Spawner) {
+///     let mut config = embassy_stm32::Config::default();
-//!     // initialize the platform...
+///     let p = embassy_stm32::init(config);
-//!     let mut config = embassy_stm32::Config::default();
+///
-//!     let p = embassy_stm32::init(config);
+///     // give the RTC to the executor...
-//!
+///     let mut rtc = Rtc::new(p.RTC, RtcConfig::default());
-//!     // give the RTC to the executor...
+///     let rtc = make_static!(rtc);
-//!     let mut rtc = Rtc::new(p.RTC, RtcConfig::default());
+///     embassy_stm32::low_power::stop_with_rtc(rtc);
-//!     let rtc = make_static!(rtc);
+///
-//!     embassy_stm32::low_power::stop_with_rtc(rtc);
+///     // your application here...
-//!
+/// }
-//!     // your application here...
+/// ```
-//! }
-//! ```
-
 use core::arch::asm;
 use core::marker::PhantomData;
 use core::sync::atomic::{compiler_fence, Ordering};
@@ -67,7 +64,6 @@ 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();
         }
@@ -79,15 +75,10 @@ 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,
@@ -96,13 +87,10 @@ 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,12 +1,9 @@
-//! 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,
@@ -16,8 +13,6 @@ pub enum OpAmpGain {
     Mul16,
 }
 
-/// Speed
-#[allow(missing_docs)]
 #[derive(Clone, Copy)]
 pub enum OpAmpSpeed {
     Normal,
@@ -185,7 +180,6 @@ impl<'d, T: Instance> Drop for OpAmpInternalOutput<'d, T> {
     }
 }
 
-/// Opamp instance trait.
 pub trait Instance: sealed::Instance + 'static {}
 
 pub(crate) mod sealed {
@@ -204,11 +198,8 @@ 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,5 +1,3 @@
-//! Enums used in QSPI configuration.
-
 #[allow(dead_code)]
 #[derive(Copy, Clone)]
 pub(crate) enum QspiMode {

embassy-stm32/src/qspi/mod.rs

@@ -14,7 +14,6 @@ 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,
@@ -46,7 +45,6 @@ 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.
@@ -73,7 +71,6 @@ impl Default for Config {
     }
 }
 
-/// QSPI driver.
 #[allow(dead_code)]
 pub struct Qspi<'d, T: Instance, Dma> {
     _peri: PeripheralRef<'d, T>,
@@ -88,7 +85,6 @@ 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,
@@ -129,7 +125,6 @@ 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,
@@ -228,7 +223,6 @@ 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));
@@ -238,7 +232,6 @@ 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));
@@ -263,7 +256,6 @@ 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))]
@@ -286,7 +278,6 @@ 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>,
@@ -319,7 +310,6 @@ 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>,
@@ -389,7 +379,6 @@ 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

@@ -80,7 +80,6 @@ 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/sdmmc/mod.rs

@@ -54,7 +54,6 @@ 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 {
@@ -71,9 +70,6 @@ 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))]
@@ -98,23 +94,17 @@ 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,
-    /// No card inserted.
+    DataCrcFail,
+    RxOverFlow,
     NoCard,
-    /// Bad clock supplied to the SDMMC peripheral.
     BadClock,
-    /// Signaling switch failed.
     SignalingSwitchFailed,
-    /// ST bit error.
+    PeripheralBusy,
     #[cfg(sdmmc_v1)]
     StBitErr,
 }
@@ -293,7 +283,6 @@ 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,
@@ -328,7 +317,6 @@ 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,
@@ -375,7 +363,6 @@ 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,
@@ -409,7 +396,6 @@ 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,
@@ -511,7 +497,7 @@ impl<'d, T: Instance, Dma: SdmmcDma<T> + 'd> Sdmmc<'d, T, Dma> {
     }
 
     /// Data transfer is in progress
-    #[inline]
+    #[inline(always)]
     fn data_active() -> bool {
         let regs = T::regs();
 
@@ -523,7 +509,7 @@ impl<'d, T: Instance, Dma: SdmmcDma<T> + 'd> Sdmmc<'d, T, Dma> {
     }
 
     /// Coammand transfer is in progress
-    #[inline]
+    #[inline(always)]
     fn cmd_active() -> bool {
         let regs = T::regs();
 
@@ -535,7 +521,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]
+    #[inline(always)]
     fn wait_idle() {
         while Self::data_active() || Self::cmd_active() {}
     }
@@ -851,7 +837,7 @@ impl<'d, T: Instance, Dma: SdmmcDma<T> + 'd> Sdmmc<'d, T, Dma> {
     }
 
     /// Clear flags in interrupt clear register
-    #[inline]
+    #[inline(always)]
     fn clear_interrupt_flags() {
         let regs = T::regs();
         regs.icr().write(|w| {
@@ -1166,8 +1152,7 @@ impl<'d, T: Instance, Dma: SdmmcDma<T> + 'd> Sdmmc<'d, T, Dma> {
         Ok(())
     }
 
-    /// Read a data block.
+    #[inline(always)]
-    #[inline]
     pub async fn read_block(&mut self, block_idx: u32, buffer: &mut DataBlock) -> Result<(), Error> {
         let card_capacity = self.card()?.card_type;
 
@@ -1219,7 +1204,6 @@ 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)?;
 
@@ -1299,7 +1283,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]
+    #[inline(always)]
     pub fn card(&self) -> Result<&Card, Error> {
         self.card.as_ref().ok_or(Error::NoCard)
     }
@@ -1435,9 +1419,7 @@ 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);
@@ -1452,10 +1434,7 @@ pin_trait!(D7Pin, Instance);
 #[cfg(sdmmc_v1)]
 dma_trait!(SdmmcDma, Instance);
 
-/// DMA instance trait.
+// SDMMCv2 uses internal DMA
-///
-/// 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)]

embassy-stm32/src/spi/mod.rs

@@ -16,38 +16,27 @@ 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,
 }
 
-/// SPI bit order
+// TODO move upwards in the tree
 #[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,
 }
 
@@ -84,7 +73,6 @@ impl Config {
     }
 }
 
-/// SPI driver.
 pub struct Spi<'d, T: Instance, Tx, Rx> {
     _peri: PeripheralRef<'d, T>,
     sck: Option<PeripheralRef<'d, AnyPin>>,
@@ -96,7 +84,6 @@ 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,
@@ -131,7 +118,6 @@ 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,
@@ -157,7 +143,6 @@ 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,
@@ -183,9 +168,6 @@ 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,
@@ -373,7 +355,6 @@ 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();
@@ -463,7 +444,6 @@ 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>,
@@ -497,7 +477,6 @@ 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>,
@@ -601,12 +580,6 @@ 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>,
@@ -615,9 +588,6 @@ 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>,
@@ -626,7 +596,6 @@ 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);
@@ -637,7 +606,6 @@ 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);
@@ -648,9 +616,6 @@ 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);
@@ -661,12 +626,6 @@ 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);
@@ -987,7 +946,6 @@ pub(crate) mod sealed {
     }
 }
 
-/// Word sizes usable for SPI.
 pub trait Word: word::Word + sealed::Word {}
 
 macro_rules! impl_word {
@@ -1067,9 +1025,7 @@ 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,17 +8,14 @@ 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,19 +13,15 @@ use crate::gpio::{AnyPin, OutputType};
 use crate::time::Hertz;
 use crate::Peripheral;
 
-/// Complementary PWM pin wrapper.
+pub struct ComplementaryPwmPin<'d, Perip, Channel> {
-///
-/// This wraps a pin to make it usable with PWM.
-pub struct ComplementaryPwmPin<'d, T, C> {
     _pin: PeripheralRef<'d, AnyPin>,
-    phantom: PhantomData<(T, C)>,
+    phantom: PhantomData<(Perip, Channel)>,
 }
 
 macro_rules! complementary_channel_impl {
     ($new_chx:ident, $channel:ident, $pin_trait:ident) => {
-        impl<'d, T: CaptureCompare16bitInstance> ComplementaryPwmPin<'d, T, $channel> {
+        impl<'d, Perip: CaptureCompare16bitInstance> ComplementaryPwmPin<'d, Perip, $channel> {
-            #[doc = concat!("Create a new ", stringify!($channel), " complementary PWM pin instance.")]
+            pub fn $new_chx(pin: impl Peripheral<P = impl $pin_trait<Perip>> + 'd, output_type: OutputType) -> Self {
-            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();
@@ -47,13 +43,11 @@ 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>>,
@@ -78,7 +72,7 @@ impl<'d, T: ComplementaryCaptureCompare16bitInstance> ComplementaryPwm<'d, T> {
         let mut this = Self { inner: tim };
 
         this.inner.set_counting_mode(counting_mode);
-        this.set_frequency(freq);
+        this.set_freq(freq);
         this.inner.start();
 
         this.inner.enable_outputs();
@@ -94,23 +88,17 @@ 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);
     }
 
-    /// Set PWM frequency.
+    pub fn set_freq(&mut self, freq: Hertz) {
-    ///
-    /// 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 {
@@ -119,22 +107,15 @@ 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,27 +17,17 @@ pub mod low_level {
 }
 
 pub(crate) mod sealed {
-    use super::*;
 
-    /// Basic 16-bit timer instance.
+    use super::*;
     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));
         }
@@ -73,9 +63,6 @@ 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();
@@ -89,17 +76,14 @@ 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();
 
@@ -111,17 +95,9 @@ 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();
 
@@ -134,29 +110,19 @@ 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);
@@ -174,7 +140,6 @@ 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();
 
@@ -186,177 +151,141 @@ 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.index();
+            let raw_channel = channel.raw();
             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.index(), false));
+            Self::regs_gp16().sr().modify(|r| r.set_ccif(channel.raw(), false));
         }
 
-        /// Enable input interrupt.
         fn enable_input_interrupt(&mut self, channel: Channel, enable: bool) {
-            Self::regs_gp16().dier().modify(|r| r.set_ccie(channel.index(), enable));
+            Self::regs_gp16().dier().modify(|r| r.set_ccie(channel.raw(), enable));
         }
-
-        /// Set input capture prescaler.
         fn set_input_capture_prescaler(&mut self, channel: Channel, factor: u8) {
-            let raw_channel = channel.index();
+            let raw_channel = channel.raw();
             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.index();
+            let raw_channel = channel.raw();
             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.index(), false);
+                    r.set_ccnp(channel.raw(), false);
-                    r.set_ccp(channel.index(), false);
+                    r.set_ccp(channel.raw(), false);
                 }
                 InputCaptureMode::Falling => {
-                    r.set_ccnp(channel.index(), false);
+                    r.set_ccnp(channel.raw(), false);
-                    r.set_ccp(channel.index(), true);
+                    r.set_ccp(channel.raw(), true);
                 }
                 InputCaptureMode::BothEdges => {
-                    r.set_ccnp(channel.index(), true);
+                    r.set_ccnp(channel.raw(), true);
-                    r.set_ccp(channel.index(), true);
+                    r.set_ccp(channel.raw(), 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.index();
+            let raw_channel: usize = channel.raw();
             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.index(), polarity.into()));
+                .modify(|w| w.set_ccp(channel.raw(), 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.index(), enable));
+            Self::regs_gp16().ccer().modify(|w| w.set_cce(channel.raw(), enable));
         }
 
-        /// Set compare value for a channel.
         fn set_compare_value(&mut self, channel: Channel, value: u16) {
-            Self::regs_gp16().ccr(channel.index()).modify(|w| w.set_ccr(value));
+            Self::regs_gp16().ccr(channel.raw()).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.index()).read().ccr()
+            Self::regs_gp16().ccr(channel.raw()).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.index()).read().ccr()
+            Self::regs_gp16().ccr(channel.raw()).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.index(), polarity.into()));
+                .modify(|w| w.set_ccnp(channel.raw(), 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.index(), enable));
+                .modify(|w| w.set_ccne(channel.raw(), 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.index()).modify(|w| w.set_ccr(value));
+            Self::regs_gp32().ccr(channel.raw()).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.index()).read().ccr()
+            Self::regs_gp32().ccr(channel.raw()).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.index()).read().ccr()
+            Self::regs_gp32().ccr(channel.raw()).read().ccr()
         }
     }
 }
 
-/// Timer channel.
 #[derive(Clone, Copy)]
 pub enum Channel {
-    /// Channel 1.
     Ch1,
-    /// Channel 2.
     Ch2,
-    /// Channel 3.
     Ch3,
-    /// Channel 4.
     Ch4,
 }
 
 impl Channel {
-    /// Get the channel index (0..3)
+    pub fn raw(&self) -> usize {
-    pub fn index(&self) -> usize {
         match self {
             Channel::Ch1 => 0,
             Channel::Ch2 => 1,
@@ -366,25 +295,17 @@ 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,
 }
 
@@ -398,7 +319,6 @@ impl From<InputTISelection> for stm32_metapac::timer::vals::CcmrInputCcs {
     }
 }
 
-/// Timer counting mode.
 #[repr(u8)]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
 pub enum CountingMode {
@@ -425,7 +345,6 @@ 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,
@@ -433,7 +352,6 @@ impl CountingMode {
         }
     }
 
-    /// Return whether this mode is center-aligned.
     pub fn is_center_aligned(&self) -> bool {
         match self {
             CountingMode::CenterAlignedDownInterrupts
@@ -468,34 +386,16 @@ 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 {
@@ -513,12 +413,9 @@ 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,
 }
 
@@ -531,31 +428,24 @@ 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,30 +9,23 @@ use crate::gpio::sealed::AFType;
 use crate::gpio::AnyPin;
 use crate::Peripheral;
 
-/// Counting direction
 pub enum Direction {
-    /// Counting up.
     Upcounting,
-    /// Counting down.
     Downcounting,
 }
 
-/// Channel 1 marker type.
+pub struct Ch1;
-pub enum Ch1 {}
+pub struct Ch2;
-/// Channel 2 marker type.
-pub enum Ch2 {}
 
-/// Wrapper for using a pin with QEI.
+pub struct QeiPin<'d, Perip, Channel> {
-pub struct QeiPin<'d, T, Channel> {
     _pin: PeripheralRef<'d, AnyPin>,
-    phantom: PhantomData<(T, Channel)>,
+    phantom: PhantomData<(Perip, Channel)>,
 }
 
 macro_rules! channel_impl {
     ($new_chx:ident, $channel:ident, $pin_trait:ident) => {
-        impl<'d, T: CaptureCompare16bitInstance> QeiPin<'d, T, $channel> {
+        impl<'d, Perip: CaptureCompare16bitInstance> QeiPin<'d, Perip, $channel> {
-            #[doc = concat!("Create a new ", stringify!($channel), " QEI pin instance.")]
+            pub fn $new_chx(pin: impl Peripheral<P = impl $pin_trait<Perip>> + 'd) -> Self {
-            pub fn $new_chx(pin: impl Peripheral<P = impl $pin_trait<T>> + 'd) -> Self {
                 into_ref!(pin);
                 critical_section::with(|_| {
                     pin.set_low();
@@ -52,13 +45,11 @@ 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)
     }
@@ -93,7 +84,6 @@ 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,
@@ -101,7 +91,6 @@ 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,28 +11,20 @@ use crate::gpio::{AnyPin, OutputType};
 use crate::time::Hertz;
 use crate::Peripheral;
 
-/// Channel 1 marker type.
+pub struct Ch1;
-pub enum Ch1 {}
+pub struct Ch2;
-/// Channel 2 marker type.
+pub struct Ch3;
-pub enum Ch2 {}
+pub struct Ch4;
-/// Channel 3 marker type.
-pub enum Ch3 {}
-/// Channel 4 marker type.
-pub enum Ch4 {}
 
-/// PWM pin wrapper.
+pub struct PwmPin<'d, Perip, Channel> {
-///
-/// This wraps a pin to make it usable with PWM.
-pub struct PwmPin<'d, T, C> {
     _pin: PeripheralRef<'d, AnyPin>,
-    phantom: PhantomData<(T, C)>,
+    phantom: PhantomData<(Perip, Channel)>,
 }
 
 macro_rules! channel_impl {
     ($new_chx:ident, $channel:ident, $pin_trait:ident) => {
-        impl<'d, T: CaptureCompare16bitInstance> PwmPin<'d, T, $channel> {
+        impl<'d, Perip: CaptureCompare16bitInstance> PwmPin<'d, Perip, $channel> {
-            #[doc = concat!("Create a new ", stringify!($channel), " PWM pin instance.")]
+            pub fn $new_chx(pin: impl Peripheral<P = impl $pin_trait<Perip>> + 'd, output_type: OutputType) -> Self {
-            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();
@@ -54,13 +46,11 @@ 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>>,
@@ -81,7 +71,7 @@ impl<'d, T: CaptureCompare16bitInstance> SimplePwm<'d, T> {
         let mut this = Self { inner: tim };
 
         this.inner.set_counting_mode(counting_mode);
-        this.set_frequency(freq);
+        this.set_freq(freq);
         this.inner.start();
 
         this.inner.enable_outputs();
@@ -97,21 +87,15 @@ 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);
     }
 
-    /// Set PWM frequency.
+    pub fn set_freq(&mut self, freq: Hertz) {
-    ///
-    /// 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 {
@@ -120,22 +104,15 @@ 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/usart/buffered.rs

@@ -82,7 +82,6 @@ impl<T: BasicInstance> interrupt::typelevel::Handler<T::Interrupt> for Interrupt
     }
 }
 
-/// Buffered UART State
 pub struct State {
     rx_waker: AtomicWaker,
     rx_buf: RingBuffer,
@@ -92,7 +91,6 @@ pub struct State {
 }
 
 impl State {
-    /// Create new state
     pub const fn new() -> Self {
         Self {
             rx_buf: RingBuffer::new(),
@@ -103,18 +101,15 @@ 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>,
 }
@@ -147,7 +142,6 @@ 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,
@@ -164,7 +158,6 @@ 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,
@@ -192,7 +185,6 @@ 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,
@@ -254,12 +246,10 @@ 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)?;
 
@@ -347,7 +337,6 @@ impl<'d, T: BasicInstance> BufferedUartRx<'d, T> {
         }
     }
 
-    /// Reconfigure the driver
     pub fn set_config(&mut self, config: &Config) -> Result<(), ConfigError> {
         reconfigure::<T>(config)?;
 
@@ -429,7 +418,6 @@ 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,6 +1,5 @@
 //! Universal Synchronous/Asynchronous Receiver Transmitter (USART, UART, LPUART)
 #![macro_use]
-#![warn(missing_docs)]
 
 use core::future::poll_fn;
 use core::marker::PhantomData;
@@ -78,29 +77,21 @@ 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,
@@ -115,37 +106,26 @@ 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,
-    /// If true: on a read-like method, if there is a latent error pending,
+    /// read will abort, the error reported and cleared
-    /// the read will abort and the error will be reported and cleared
+    /// if false, the error is ignored 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 receiver’s tolerance to clock deviations,
+    /// This will increase the receivers tolerance to clock deviations,
     /// but will effectively disable noise detection.
     #[cfg(not(usart_v1))]
     pub assume_noise_free: bool,
@@ -208,7 +188,6 @@ 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>,
@@ -224,7 +203,6 @@ 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>,
@@ -239,7 +217,6 @@ 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>,
@@ -270,7 +247,6 @@ 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,
@@ -312,12 +288,10 @@ 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>,
@@ -334,7 +308,6 @@ 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 {
@@ -344,7 +317,6 @@ 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() {}
@@ -366,7 +338,6 @@ 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,
@@ -416,7 +387,6 @@ 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)
     }
@@ -474,7 +444,6 @@ 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>,
@@ -484,7 +453,6 @@ 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()? {
@@ -494,7 +462,6 @@ 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 {
@@ -504,7 +471,6 @@ 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>,
@@ -729,7 +695,6 @@ 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,
@@ -746,7 +711,6 @@ 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,
@@ -774,7 +738,6 @@ 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,
@@ -850,7 +813,6 @@ 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>,
@@ -858,17 +820,14 @@ 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>,
@@ -876,17 +835,14 @@ 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>,
@@ -1336,10 +1292,8 @@ 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,7 +11,6 @@ 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>,
@@ -28,8 +27,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 losing bytes. The `dma_buf` is a buffer registered to the
+    /// without the possibility of loosing bytes. The `dma_buf` is a buffer registered to the
-    /// DMA controller, and must be large enough to prevent overflows.
+    /// DMA controller, and must be sufficiently large, such that it will not overflow.
     pub fn into_ring_buffered(self, dma_buf: &'d mut [u8]) -> RingBufferedUartRx<'d, T, RxDma> {
         assert!(!dma_buf.is_empty() && dma_buf.len() <= 0xFFFF);
 
@@ -50,7 +49,6 @@ 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();
@@ -66,7 +64,6 @@ 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,5 +1,3 @@
-//! Universal Serial Bus (USB)
-
 use crate::interrupt;
 use crate::rcc::RccPeripheral;
 
@@ -12,9 +10,7 @@ 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,7 +244,6 @@ struct EndpointData {
     used_out: bool,
 }
 
-/// USB driver.
 pub struct Driver<'d, T: Instance> {
     phantom: PhantomData<&'d mut T>,
     alloc: [EndpointData; EP_COUNT],
@@ -252,7 +251,6 @@ 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,
@@ -467,7 +465,6 @@ 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],
@@ -643,7 +640,6 @@ trait Dir {
     fn waker(i: usize) -> &'static AtomicWaker;
 }
 
-/// Marker type for the "IN" direction.
 pub enum In {}
 impl Dir for In {
     fn dir() -> Direction {
@@ -656,7 +652,6 @@ impl Dir for In {
     }
 }
 
-/// Marker type for the "OUT" direction.
 pub enum Out {}
 impl Dir for Out {
     fn dir() -> Direction {
@@ -669,7 +664,6 @@ impl Dir for Out {
     }
 }
 
-/// USB endpoint.
 pub struct Endpoint<'d, T: Instance, D> {
     _phantom: PhantomData<(&'d mut T, D)>,
     info: EndpointInfo,
@@ -819,7 +813,6 @@ 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

@@ -20,9 +20,7 @@ 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,7 +204,6 @@ 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,
@@ -212,7 +211,6 @@ impl PhyType {
         }
     }
 
-    /// Get whether this PHY is any of the high-speed types.
     pub fn high_speed(&self) -> bool {
         match self {
             PhyType::InternalFullSpeed => false,
@@ -220,7 +218,7 @@ impl PhyType {
         }
     }
 
-    fn to_dspd(&self) -> vals::Dspd {
+    pub fn to_dspd(&self) -> vals::Dspd {
         match self {
             PhyType::InternalFullSpeed => vals::Dspd::FULL_SPEED_INTERNAL,
             PhyType::InternalHighSpeed => vals::Dspd::HIGH_SPEED,
@@ -232,7 +230,6 @@ 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]>,
@@ -250,7 +247,6 @@ 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 _);
@@ -275,7 +271,6 @@ struct EndpointData {
     fifo_size_words: u16,
 }
 
-/// USB driver config.
 #[non_exhaustive]
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]
 pub struct Config {
@@ -302,7 +297,6 @@ impl Default for Config {
     }
 }
 
-/// USB driver.
 pub struct Driver<'d, T: Instance> {
     config: Config,
     phantom: PhantomData<&'d mut T>,
@@ -533,7 +527,6 @@ 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>,
@@ -1099,7 +1092,6 @@ trait Dir {
     fn dir() -> Direction;
 }
 
-/// Marker type for the "IN" direction.
 pub enum In {}
 impl Dir for In {
     fn dir() -> Direction {
@@ -1107,7 +1099,6 @@ impl Dir for In {
     }
 }
 
-/// Marker type for the "OUT" direction.
 pub enum Out {}
 impl Dir for Out {
     fn dir() -> Direction {
@@ -1115,7 +1106,6 @@ impl Dir for Out {
     }
 }
 
-/// USB endpoint.
 pub struct Endpoint<'d, T: Instance, D> {
     _phantom: PhantomData<(&'d mut T, D)>,
     info: EndpointInfo,
@@ -1309,7 +1299,6 @@ 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

@@ -6,7 +6,6 @@ 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>,
 }
@@ -65,12 +64,10 @@ 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));
     }
@@ -82,7 +79,6 @@ mod sealed {
     }
 }
 
-/// IWDG instance trait.
 pub trait Instance: sealed::Instance {}
 
 foreach_peripheral!(

examples/stm32f4/src/bin/ws2812_pwm_dma.rs

@@ -110,7 +110,7 @@ async fn main(_spawner: Spawner) {
                     &mut dp.DMA1_CH2,
                     5,
                     color_list[color_list_index],
-                    pac::TIM3.ccr(pwm_channel.index()).as_ptr() as *mut _,
+                    pac::TIM3.ccr(pwm_channel.raw()).as_ptr() as *mut _,
                     dma_transfer_option,
                 )
                 .await;

examples/stm32h7/src/bin/low_level_timer_api.rs

@@ -85,7 +85,7 @@ impl<'d, T: CaptureCompare32bitInstance> SimplePwm32<'d, T> {
 
         let mut this = Self { inner: tim };
 
-        this.set_frequency(freq);
+        this.set_freq(freq);
         this.inner.start();
 
         let r = T::regs_gp32();
@@ -102,14 +102,14 @@ impl<'d, T: CaptureCompare32bitInstance> SimplePwm32<'d, T> {
     }
 
     pub fn enable(&mut self, channel: Channel) {
-        T::regs_gp32().ccer().modify(|w| w.set_cce(channel.index(), true));
+        T::regs_gp32().ccer().modify(|w| w.set_cce(channel.raw(), true));
     }
 
     pub fn disable(&mut self, channel: Channel) {
-        T::regs_gp32().ccer().modify(|w| w.set_cce(channel.index(), false));
+        T::regs_gp32().ccer().modify(|w| w.set_cce(channel.raw(), false));
     }
 
-    pub fn set_frequency(&mut self, freq: Hertz) {
+    pub fn set_freq(&mut self, freq: Hertz) {
         <T as embassy_stm32::timer::low_level::GeneralPurpose32bitInstance>::set_frequency(&mut self.inner, freq);
     }
 
@@ -119,6 +119,6 @@ impl<'d, T: CaptureCompare32bitInstance> SimplePwm32<'d, T> {
 
     pub fn set_duty(&mut self, channel: Channel, duty: u32) {
         defmt::assert!(duty < self.get_max_duty());
-        T::regs_gp32().ccr(channel.index()).modify(|w| w.set_ccr(duty))
+        T::regs_gp32().ccr(channel.raw()).modify(|w| w.set_ccr(duty))
     }
 }