More validation and # Errors entries (#3074)

* WIP

* updates

* upd

* +spi

* fmt + lint

* rework `Exact` setting

* Reviews + spi failed experiment

* clean

* address reviews, roll back SPI changes

* rebase

* small fixes

* address reviews

* reviews

fmt

Rebase

dumb

* address reviews

unstable: macro -> feat

esp-hal/CHANGELOG.md

@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `esp_hal::time::{Rate, Duration, Instant}` (#3083)
 - Async support for ADC oneshot reads for ESP32C2, ESP32C3, ESP32C6 and ESP32H2 (#2925, #3082)
 - `ESP_HAL_CONFIG_XTAL_FREQUENCY` configuration. For now, chips other than ESP32 and ESP32-C2 have a single option only. (#3054)
+- Added more validation to UART and SPI. User can now specify the baudrate tolerance of UART config (#3074)
 
 ### Changed
 

esp-hal/src/gpio/mod.rs

@@ -1262,7 +1262,6 @@ impl<'d> Output<'d> {
     }
 
     /// Change the configuration.
-    // FIXME: when https://github.com/esp-rs/esp-hal/issues/2839 is resolved, add an appropriate `# Error` entry.
     #[inline]
     pub fn apply_config(&mut self, config: &OutputConfig) {
         self.pin.apply_output_config(config)
@@ -1451,7 +1450,6 @@ impl<'d> Input<'d> {
     }
 
     /// Change the configuration.
-    // FIXME: when https://github.com/esp-rs/esp-hal/issues/2839 is resolved, add an appropriate `# Error` entry.
     pub fn apply_config(&mut self, config: &InputConfig) {
         self.pin.apply_input_config(config)
     }

esp-hal/src/lcd_cam/cam.rs

@@ -166,6 +166,11 @@ impl<'d> Camera<'d> {
     }
 
     /// Applies the configuration to the camera interface.
+    ///
+    /// # Errors
+    ///
+    /// [`ConfigError::Clock`] will be returned if the frequency passed in
+    /// `Config` is too low.
     pub fn apply_config(&mut self, config: &Config) -> Result<(), ConfigError> {
         let clocks = Clocks::get();
         let (i, divider) = calculate_clkm(

esp-hal/src/lcd_cam/lcd/dpi.rs

@@ -169,6 +169,11 @@ where
     }
 
     /// Applies the configuration to the peripheral.
+    ///
+    /// # Errors
+    ///
+    /// [`ConfigError::Clock`] variant will be returned if the frequency passed
+    /// in `Config` is too low.
     pub fn apply_config(&mut self, config: &Config) -> Result<(), ConfigError> {
         let clocks = Clocks::get();
         // Due to https://www.espressif.com/sites/default/files/documentation/esp32-s3_errata_en.pdf

esp-hal/src/lcd_cam/lcd/i8080.rs

@@ -134,6 +134,11 @@ where
     }
 
     /// Applies configuration.
+    ///
+    /// # Errors
+    ///
+    /// [`ConfigError::Clock`] variant will be returned if the frequency passed
+    /// in `Config` is too low.
     pub fn apply_config(&mut self, config: &Config) -> Result<(), ConfigError> {
         let clocks = Clocks::get();
         // Due to https://www.espressif.com/sites/default/files/documentation/esp32-s3_errata_en.pdf

esp-hal/src/spi/master.rs

@@ -585,6 +585,21 @@ impl Config {
     fn raw_clock_reg_value(&self) -> Result<u32, ConfigError> {
         self.reg
     }
+
+    fn validate(&self) -> Result<(), ConfigError> {
+        cfg_if::cfg_if! {
+            if #[cfg(esp32h2)] {
+                if self.frequency < Rate::from_khz(70) || self.frequency > Rate::from_mhz(48) {
+                    return Err(ConfigError::UnsupportedFrequency);
+                }
+            } else {
+                if self.frequency < Rate::from_khz(70) || self.frequency > Rate::from_mhz(80) {
+                    return Err(ConfigError::UnsupportedFrequency);
+                }
+            }
+        }
+        Ok(())
+    }
 }
 
 #[derive(Debug)]
@@ -602,7 +617,22 @@ struct SpiPinGuard {
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-pub enum ConfigError {}
+pub enum ConfigError {
+    /// The requested frequency is not supported.
+    UnsupportedFrequency,
+}
+
+impl core::error::Error for ConfigError {}
+
+impl core::fmt::Display for ConfigError {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        match self {
+            ConfigError::UnsupportedFrequency => {
+                write!(f, "The requested frequency is not supported")
+            }
+        }
+    }
+}
 
 /// SPI peripheral driver
 ///
@@ -666,7 +696,10 @@ where
 
 impl<'d> Spi<'d, Blocking> {
     /// Constructs an SPI instance in 8bit dataframe mode.
-    // FIXME: when https://github.com/esp-rs/esp-hal/issues/2839 is resolved, add an appropriate `# Error` entry.
+    ///
+    /// # Errors
+    ///
+    /// See [`Spi::apply_config`].
     pub fn new(
         spi: impl Peripheral<P = impl PeripheralInstance> + 'd,
         config: Config,
@@ -983,7 +1016,14 @@ where
     }
 
     /// Change the bus configuration.
-    // FIXME: when https://github.com/esp-rs/esp-hal/issues/2839 is resolved, add an appropriate `# Error` entry.
+    ///
+    /// # Errors
+    ///
+    /// If frequency passed in config exceeds
+    #[cfg_attr(not(esp32h2), doc = " 80MHz")]
+    #[cfg_attr(esp32h2, doc = " 48MHz")]
+    /// or is below 70kHz,
+    /// [`ConfigError::UnsupportedFrequency`] error will be returned.
     pub fn apply_config(&mut self, config: &Config) -> Result<(), ConfigError> {
         self.driver().apply_config(config)
     }
@@ -1071,9 +1111,10 @@ where
     ///
     /// # Errors
     ///
-    /// The corresponding error variant from [`Error`] will be returned if
+    /// [`Error::FifoSizeExeeded`] or [`Error::Unsupported`] will be returned if
     /// passed buffer is bigger than FIFO size or if buffer is empty (currently
-    /// unsupported).
+    /// unsupported). `DataMode::Single` cannot be combined with any other
+    /// [`DataMode`], otherwise [`Error::Unsupported`] will be returned.
     #[instability::unstable]
     pub fn half_duplex_read(
         &mut self,
@@ -1111,7 +1152,7 @@ where
     ///
     /// # Errors
     ///
-    /// The corresponding error variant from [`Error`] will be returned if
+    /// [`Error::FifoSizeExeeded`] will be returned if
     /// passed buffer is bigger than FIFO size.
     #[cfg_attr(
         esp32,
@@ -1554,7 +1595,14 @@ mod dma {
         }
 
         /// Change the bus configuration.
-        // FIXME: when https://github.com/esp-rs/esp-hal/issues/2839 is resolved, add an appropriate `# Error` entry.
+        ///
+        /// # Errors
+        ///
+        /// If frequency passed in config exceeds
+        #[cfg_attr(not(esp32h2), doc = " 80MHz")]
+        #[cfg_attr(esp32h2, doc = " 48MHz")]
+        /// or is below 70kHz,
+        /// [`ConfigError::UnsupportedFrequency`] error will be returned.
         #[instability::unstable]
         pub fn apply_config(&mut self, config: &Config) -> Result<(), ConfigError> {
             self.driver().apply_config(config)
@@ -2017,7 +2065,14 @@ mod dma {
         }
 
         /// Change the bus configuration.
-        // FIXME: when https://github.com/esp-rs/esp-hal/issues/2839 is resolved, add an appropriate `# Error` entry.
+        ///
+        /// # Errors
+        ///
+        /// If frequency passed in config exceeds
+        #[cfg_attr(not(esp32h2), doc = " 80MHz")]
+        #[cfg_attr(esp32h2, doc = " 48MHz")]
+        /// or is below 70kHz,
+        /// [`ConfigError::UnsupportedFrequency`] error will be returned.
         #[instability::unstable]
         pub fn apply_config(&mut self, config: &Config) -> Result<(), ConfigError> {
             self.spi_dma.apply_config(config)
@@ -3064,6 +3119,7 @@ impl Driver {
     }
 
     fn apply_config(&self, config: &Config) -> Result<(), ConfigError> {
+        config.validate()?;
         self.ch_bus_freq(config)?;
         self.set_bit_order(config.read_bit_order, config.write_bit_order);
         self.set_data_mode(config.mode);