document-features

Author: burrbull

Cargo.toml

@@ -49,6 +49,7 @@ systick-monotonic = { version = "1.0", optional = true }
 enumflags2 = "0.7.8"
 embedded-storage = "0.3"
 vcell = "0.1.3"
+document-features = "0.2"
 
 [dependencies.time]
 version = "0.3.14"
@@ -98,6 +99,11 @@ default-features = false
 features = ["macros"]
 
 [features]
+#! Use one of the supported STM32-serie related features:
+#! `stm32f401`, `stm32f405`, `stm32f407`, `stm32f415`, `stm32f417`, `stm32f410`,
+#! `stm32f411`, `stm32f412`, `stm32f413`, `stm32f423`, `stm32f427`, `stm32f429`,
+#! `stm32f437`, `stm32f439`, `stm32f446`, `stm32f469`, `stm32f479`.
+
 # Note: stm32f4 has only one feature for some very similar device families,
 # so it's intended for e.g. stm32f405/415 to both enable stm32f4/stm32f405.
 stm32f401 = ["stm32f4/stm32f401"]
@@ -118,18 +124,28 @@ stm32f446 = ["stm32f4/stm32f446"]
 stm32f469 = ["stm32f4/stm32f469"]
 stm32f479 = ["stm32f4/stm32f469"]
 
-usb_fs = ["synopsys-usb-otg", "synopsys-usb-otg/fs"]
-usb_hs = ["synopsys-usb-otg", "synopsys-usb-otg/hs"]
+## Support monotonic timers that can be used by [RTIC framework](https://crates.io/crates/cortex-m-rtic)
+rtic = ["dep:rtic-monotonic", "dep:systick-monotonic"]
+
+## Implementation of `defmt::Format` for public enums and structures. See [defmt](https://crates.io/crates/defmt)
+defmt = ["dep:defmt", "fugit/defmt", "nb/defmt-0-3"]
 
-can = ["bxcan"]
+## bxCAN peripheral support. See [bxcan](https://crates.io/crates/bxcan)
+can = ["dep:bxcan"]
 
-i2s = ["stm32_i2s_v12x"]
+## I2S peripheral support. See [stm32_i2s_v12x](https://crates.io/crates/stm32_i2s_v12x)
+i2s = ["dep:stm32_i2s_v12x"]
 
-fsmc_lcd = ["display-interface"]
+## USB OTG-FS peripheral support. See [synopsys-usb-otg](https://crates.io/crates/synopsys-usb-otg)
+usb_fs = ["dep:synopsys-usb-otg", "synopsys-usb-otg/fs"]
+## USB OTG-HS peripheral support. See [synopsys-usb-otg](https://crates.io/crates/synopsys-usb-otg)
+usb_hs = ["dep:synopsys-usb-otg", "synopsys-usb-otg/hs"]
 
-defmt = ["dep:defmt", "fugit/defmt", "nb/defmt-0-3"]
+## LCD support via FMC/FSMC peripheral. See [display-interface](https://crates.io/crates/display-interface)
+fsmc_lcd = ["dep:display-interface"]
 
-rtic = ["rtic-monotonic", "systick-monotonic"]
+## SDIO peripheral support. See [sdio-host](https://crates.io/crates/sdio-host)
+sdio-host = ["dep:sdio-host"]
 
 [profile.dev]
 debug = true

src/i2s.rs

@@ -12,8 +12,8 @@ use crate::pac;
 use crate::rcc::{self, Clocks, Reset};
 use fugit::HertzU32 as Hertz;
 
-#[cfg(feature = "stm32_i2s_v12x")]
-pub extern crate stm32_i2s_v12x;
+#[cfg(feature = "i2s")]
+pub use stm32_i2s_v12x;
 
 // I2S pins are mostly the same as the corresponding SPI pins:
 // MOSI -> SD
@@ -202,7 +202,7 @@ macro_rules! i2s {
             }
         }
 
-        #[cfg(feature = "stm32_i2s_v12x")]
+        #[cfg(feature = "i2s")]
         impl stm32_i2s_v12x::WsPin for gpio::alt::$i2s::Ws {
             fn is_high(&self) -> bool {
                 use crate::gpio::ReadPin;
@@ -214,7 +214,7 @@ macro_rules! i2s {
             }
         }
 
-        #[cfg(feature = "stm32_i2s_v12x")]
+        #[cfg(feature = "i2s")]
         unsafe impl stm32_i2s_v12x::I2sPeripheral for I2s<$SPI>
         where
             $SPI: rcc::Reset,
@@ -375,7 +375,7 @@ macro_rules! dual_i2s {
             type I2sExtPeripheral = $I2SEXT;
         }
 
-        #[cfg(feature = "stm32_i2s_v12x")]
+        #[cfg(feature = "i2s")]
         unsafe impl stm32_i2s_v12x::DualI2sPeripheral for DualI2s<$SPI>
         where
             $SPI: rcc::Reset,
@@ -420,7 +420,7 @@ dual_i2s!(pac::SPI3, pac::I2S3EXT, DualI2s3, i2s3, i2s_clk);
 dual_i2s!(pac::SPI3, pac::I2S3EXT, DualI2s3, i2s3, i2s_apb1_clk);
 
 // DMA support: reuse existing mappings for SPI
-#[cfg(feature = "stm32_i2s_v12x")]
+#[cfg(feature = "i2s")]
 mod dma {
     use super::*;
     use crate::dma::traits::{DMASet, PeriAddress};

src/lib.rs

@@ -1,3 +1,7 @@
+//! Multi device hardware abstraction on top of the peripheral access API for the STMicro STM32F4 series microcontrollers.
+//!
+//! ## Feature flags
+#![doc = document_features::document_features!()]
 #![no_std]
 #![allow(non_camel_case_types)]
 
@@ -93,7 +97,7 @@ pub mod i2c;
 pub mod i2s;
 #[cfg(all(feature = "usb_fs", pac_otg_fs))]
 pub mod otg_fs;
-#[cfg(all(any(feature = "usb_hs", docsrs), pac_otg_hs,))]
+#[cfg(all(any(feature = "usb_hs", docsrs), pac_otg_hs))]
 pub mod otg_hs;
 
 #[cfg(pac_rng)]

src/rcc/mod.rs

@@ -302,7 +302,7 @@ impl RccExt for RCC {
                 sysclk: None,
                 pll48clk: false,
                 i2s_ckin: None,
-                #[cfg(any(gpio_f401, gpio_f410, gpio_f411, gpio_f417, gpio_f427, gpio_f469,))]
+                #[cfg(any(gpio_f401, gpio_f410, gpio_f411, gpio_f417, gpio_f427, gpio_f469))]
                 i2s_clk: None,
                 #[cfg(any(gpio_f412, gpio_f413, gpio_f446))]
                 i2s_apb1_clk: None,
@@ -343,15 +343,15 @@ pub const SYSCLK_MAX: u32 = 84_000_000;
 /// Maximum system clock frequency
 pub const SYSCLK_MAX: u32 = 168_000_000;
 
-#[cfg(any(gpio_f410, gpio_f411, gpio_f412, gpio_f413,))]
+#[cfg(any(gpio_f410, gpio_f411, gpio_f412, gpio_f413))]
 /// Maximum system clock frequency
 pub const SYSCLK_MAX: u32 = 100_000_000;
 
 #[cfg(any(gpio_f427, gpio_f446, gpio_f469))]
 /// Maximum system clock frequency
 pub const SYSCLK_MAX: u32 = 180_000_000;
 
-#[cfg(any(gpio_f401, gpio_f410, gpio_f411, gpio_f412, gpio_f413,))]
+#[cfg(any(gpio_f401, gpio_f410, gpio_f411, gpio_f412, gpio_f413))]
 /// Maximum APB2 peripheral clock frequency
 pub const PCLK2_MAX: u32 = SYSCLK_MAX;
 
@@ -372,7 +372,7 @@ pub struct CFGR {
     pll48clk: bool,
 
     i2s_ckin: Option<u32>,
-    #[cfg(any(gpio_f401, gpio_f410, gpio_f411, gpio_f417, gpio_f427, gpio_f469,))]
+    #[cfg(any(gpio_f401, gpio_f410, gpio_f411, gpio_f417, gpio_f427, gpio_f469))]
     i2s_clk: Option<u32>,
     #[cfg(any(gpio_f412, gpio_f413, gpio_f446))]
     i2s_apb1_clk: Option<u32>,
@@ -441,7 +441,7 @@ impl CFGR {
     }
 
     /// Selects an I2S clock frequency and enables the I2S clock.
-    #[cfg(any(gpio_f401, gpio_f410, gpio_f411, gpio_f417, gpio_f427, gpio_f469,))]
+    #[cfg(any(gpio_f401, gpio_f410, gpio_f411, gpio_f417, gpio_f427, gpio_f469))]
     pub fn i2s_clk(mut self, freq: Hertz) -> Self {
         self.i2s_clk = Some(freq.raw());
         self
@@ -596,7 +596,7 @@ impl CFGR {
         }
     }
 
-    #[cfg(any(gpio_f401, gpio_f417, gpio_f427, gpio_f469,))]
+    #[cfg(any(gpio_f401, gpio_f417, gpio_f427, gpio_f469))]
     #[inline(always)]
     fn pll_setup(&self, pllsrcclk: u32, pllsysclk: Option<u32>) -> PllSetup {
         let i2s_clocks = self.i2s_clocks();

src/spi.rs

@@ -4,7 +4,7 @@ use core::ops::{Deref, DerefMut};
 use crate::dma::traits::{DMASet, PeriAddress};
 use crate::dma::{MemoryToPeripheral, PeripheralToMemory};
 use crate::gpio::{self, NoPin};
-use crate::{pac, ReadFlags};
+use crate::pac;
 
 /// Clock polarity
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]