Resolve C-FAILURE violations

esp-hal/src/gpio/mod.rs

@@ -743,6 +743,11 @@ impl Io {
     }
 
     /// Set the interrupt priority for GPIO interrupts.
+    ///
+    /// # Panics
+    ///
+    /// Panics if passed interrupt handler is invalid (e.g. has priority
+    /// `None`)
     #[instability::unstable]
     pub fn set_interrupt_priority(&self, prio: Priority) {
         unwrap!(interrupt::enable(Interrupt::GPIO, prio));
@@ -761,6 +766,11 @@ impl Io {
     /// we clear the interrupt status register for you. This is NOT the case
     /// if you register the interrupt handler directly, by defining a
     /// `#[no_mangle] unsafe extern "C" fn GPIO()` function.
+    ///
+    /// # Panics
+    ///
+    /// Panics if passed interrupt handler is invalid (e.g. has priority
+    /// `None`)
     #[instability::unstable]
     pub fn set_interrupt_handler(&mut self, handler: InterruptHandler) {
         for core in crate::Cpu::other() {
@@ -1173,6 +1183,7 @@ impl<'d> Output<'d> {
     /// blink_once(&mut led, &mut delay);
     /// # }
     /// ```
+    // FIXME: when https://github.com/esp-rs/esp-hal/issues/2839 is resolved, add an appropriate `# Error` entry.
     #[inline]
     pub fn new(
         pin: impl Peripheral<P = impl OutputPin> + 'd,
@@ -1247,6 +1258,7 @@ 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)
@@ -1384,6 +1396,7 @@ impl<'d> Input<'d> {
     /// print_when_pressed(&mut button, &mut delay);
     /// # }
     /// ```
+    // FIXME: when https://github.com/esp-rs/esp-hal/issues/2839 is resolved, add an appropriate `# Error` entry.
     #[inline]
     pub fn new(pin: impl Peripheral<P = impl InputPin> + 'd, config: InputConfig) -> Self {
         let mut pin = Flex::new(pin);
@@ -1432,6 +1445,7 @@ 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)
     }
@@ -1536,6 +1550,11 @@ impl<'d> Input<'d> {
     /// Enable as a wake-up source.
     ///
     /// This will unlisten for interrupts
+    ///
+    /// # Error
+    /// Configuring pin to wake up from light sleep on an edge
+    /// trigger is currently not supported, corresponding variant of
+    /// [`WakeConfigError`] will be returned.
     #[instability::unstable]
     #[inline]
     pub fn wakeup_enable(&mut self, enable: bool, event: WakeEvent) -> Result<(), WakeConfigError> {
@@ -1746,6 +1765,11 @@ impl<'d> Flex<'d> {
     /// Enable as a wake-up source.
     ///
     /// This will unlisten for interrupts
+    ///
+    /// # Error
+    /// Configuring pin to wake up from light sleep on an edge
+    /// trigger is currently not supported, corresponding variant of
+    /// [`WakeConfigError`] will be returned.
     #[inline]
     #[instability::unstable]
     pub fn wakeup_enable(&mut self, enable: bool, event: WakeEvent) -> Result<(), WakeConfigError> {

esp-hal/src/i2c/master/mod.rs

@@ -496,6 +496,11 @@ impl<'d, Dm: DriverMode> I2c<'d, Dm> {
     }
 
     /// Applies a new configuration.
+    ///
+    /// # Errors
+    ///
+    /// A [`ConfigError`] variant will be returned if bus frequency or timeout
+    /// passed in config is invalid.
     pub fn apply_config(&mut self, config: &Config) -> Result<(), ConfigError> {
         self.driver().setup(config)?;
         self.config = *config;
@@ -595,6 +600,11 @@ impl<'d, Dm: DriverMode> I2c<'d, Dm> {
 
 impl<'d> I2c<'d, Blocking> {
     /// Create a new I2C instance.
+    ///
+    /// # Errors
+    ///
+    /// A [`ConfigError`] variant will be returned if bus frequency or timeout
+    /// passed in config is invalid.
     pub fn new(
         i2c: impl Peripheral<P = impl Instance> + 'd,
         config: Config,
@@ -634,6 +644,11 @@ impl<'d> I2c<'d, Blocking> {
     ///
     /// You can restore the default/unhandled interrupt handler by using
     /// [crate::DEFAULT_INTERRUPT_HANDLER]
+    ///
+    /// # Panics
+    ///
+    /// Panics if passed interrupt handler is invalid (e.g. has priority
+    /// `None`)
     #[instability::unstable]
     pub fn set_interrupt_handler(&mut self, handler: InterruptHandler) {
         self.i2c.info().set_interrupt_handler(handler);
@@ -710,6 +725,10 @@ impl<'d> I2c<'d, Blocking> {
     /// i2c.read(DEVICE_ADDR, &mut data).ok();
     /// # }
     /// ```
+    /// 
+    /// # Errors
+    ///
+    /// The corresponding error variant from [`Error`] will be returned if the passed buffer has zero length.
     pub fn read<A: Into<I2cAddress>>(
         &mut self,
         address: A,
@@ -735,6 +754,10 @@ impl<'d> I2c<'d, Blocking> {
     /// i2c.write_read(DEVICE_ADDR, &[0xaa], &mut data).ok();
     /// # }
     /// ```
+    /// 
+    /// # Errors
+    ///
+    /// The corresponding error variant from [`Error`] will be returned if the passed buffer has zero length.
     pub fn write_read<A: Into<I2cAddress>>(
         &mut self,
         address: A,
@@ -789,6 +812,10 @@ impl<'d> I2c<'d, Blocking> {
     /// ).ok();
     /// # }
     /// ```
+    /// 
+    /// # Errors
+    ///
+    /// The corresponding error variant from [`Error`] will be returned if the buffer passed to an [`Operation`] has zero length.
     pub fn transaction<'a, A: Into<I2cAddress>>(
         &mut self,
         address: A,
@@ -944,6 +971,11 @@ impl<'d> I2c<'d, Async> {
     }
 
     /// Reads enough bytes from slave with `address` to fill `buffer`
+    ///
+    /// # Errors
+    ///
+    /// The corresponding error variant from [`Error`] will be returned if the
+    /// passed buffer has zero length.
     pub async fn read<A: Into<I2cAddress>>(
         &mut self,
         address: A,
@@ -957,6 +989,11 @@ impl<'d> I2c<'d, Async> {
 
     /// Writes bytes to slave with address `address` and then reads enough
     /// bytes to fill `buffer` *in a single transaction*
+    ///
+    /// # Errors
+    ///
+    /// The corresponding error variant from [`Error`] will be returned if the
+    /// passed buffer has zero length.
     pub async fn write_read<A: Into<I2cAddress>>(
         &mut self,
         address: A,
@@ -997,6 +1034,11 @@ impl<'d> I2c<'d, Async> {
     ///   to indicate writing
     /// - `SR` = repeated start condition
     /// - `SP` = stop condition
+    ///
+    /// # Errors
+    ///
+    /// The corresponding error variant from [`Error`] will be returned if the
+    /// buffer passed to an [`Operation`] has zero length.
     pub async fn transaction<'a, A: Into<I2cAddress>>(
         &mut self,
         address: A,

esp-hal/src/spi/master.rs

@@ -534,6 +534,7 @@ 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.
     pub fn new(
         spi: impl Peripheral<P = impl PeripheralInstance> + 'd,
         config: Config,
@@ -658,6 +659,11 @@ impl<'d> Spi<'d, Blocking> {
     ///
     /// You can restore the default/unhandled interrupt handler by using
     /// [crate::interrupt::DEFAULT_INTERRUPT_HANDLER]
+    ///
+    /// # Panics
+    ///
+    /// Panics if passed interrupt handler is invalid (e.g. has priority
+    /// `None`)
     #[instability::unstable]
     pub fn set_interrupt_handler(&mut self, handler: InterruptHandler) {
         let interrupt = self.driver().info.interrupt;
@@ -843,6 +849,7 @@ where
     }
 
     /// Change the bus 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: &Config) -> Result<(), ConfigError> {
         self.driver().apply_config(config)
     }
@@ -928,6 +935,12 @@ where
     Dm: DriverMode,
 {
     /// Half-duplex read.
+    ///
+    /// # Errors
+    ///
+    /// The corresponding error variant from [`Error`] will be returned if
+    /// passed buffer is bigger than FIFO size or if buffer is empty (currently
+    /// unsupported).
     #[instability::unstable]
     pub fn half_duplex_read(
         &mut self,
@@ -962,6 +975,15 @@ where
     }
 
     /// Half-duplex write.
+    ///
+    /// # Errors
+    ///
+    /// The corresponding error variant from [`Error`] will be returned if
+    /// passed buffer is bigger than FIFO size.
+    #[cfg_attr(
+        esp32,
+        doc = "Dummy phase configuration is currently not supported, only value `0` is valid (see issue [#2240](https://github.com/esp-rs/esp-hal/issues/2240))."
+    )]
     #[instability::unstable]
     pub fn half_duplex_write(
         &mut self,
@@ -1402,6 +1424,7 @@ mod dma {
         }
 
         /// Change the bus configuration.
+        // FIXME: when https://github.com/esp-rs/esp-hal/issues/2839 is resolved, add an appropriate `# Error` entry.
         #[instability::unstable]
         pub fn apply_config(&mut self, config: &Config) -> Result<(), ConfigError> {
             self.driver().apply_config(config)
@@ -1864,6 +1887,7 @@ mod dma {
         }
 
         /// Change the bus configuration.
+        // FIXME: when https://github.com/esp-rs/esp-hal/issues/2839 is resolved, add an appropriate `# Error` entry.
         #[instability::unstable]
         pub fn apply_config(&mut self, config: &Config) -> Result<(), ConfigError> {
             self.spi_dma.apply_config(config)

esp-hal/src/uart.rs

@@ -559,6 +559,7 @@ where
     /// Change the configuration.
     ///
     /// Note that this also changes the configuration of the RX half.
+    // FIXME: when https://github.com/esp-rs/esp-hal/issues/2839 is resolved, add an appropriate `# Error` entry.
     #[instability::unstable]
     pub fn apply_config(&mut self, _config: &Config) -> Result<(), ConfigError> {
         // Nothing to do so far.
@@ -752,6 +753,7 @@ where
     /// Change the configuration.
     ///
     /// Note that this also changes the configuration of the TX half.
+    // FIXME: when https://github.com/esp-rs/esp-hal/issues/2839 is resolved, add an appropriate `# Error` entry.
     #[instability::unstable]
     pub fn apply_config(&mut self, config: &Config) -> Result<(), ConfigError> {
         self.uart
@@ -986,6 +988,7 @@ impl<'d> Uart<'d, Blocking> {
     /// .with_tx(peripherals.GPIO2);
     /// # }
     /// ```
+    // FIXME: when https://github.com/esp-rs/esp-hal/issues/2839 is resolved, add an appropriate `# Error` entry.
     pub fn new(
         uart: impl Peripheral<P = impl Instance> + 'd,
         config: Config,
@@ -1176,6 +1179,7 @@ where
     }
 
     /// 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: &Config) -> Result<(), ConfigError> {
         self.rx.apply_config(config)?;
         self.tx.apply_config(config)?;
@@ -1853,6 +1857,12 @@ pub mod lp_uart {
 
     impl LpUart {
         /// Initialize the UART driver using the provided configuration
+        ///
+        /// # Panics
+        ///  
+        /// [`Apb`] is a wrong clock source for LP_UART
+        ///
+        /// [`Apb`]: super::ClockSource::Apb
         // TODO: CTS and RTS pins
         pub fn new(
             uart: LP_UART,
@@ -1988,6 +1998,12 @@ pub mod lp_uart {
         }
 
         /// Modify UART baud rate and reset TX/RX fifo.
+        ///
+        /// # Panics
+        ///
+        /// [`Apb`] is a wrong clock source for LP_UART
+        ///
+        /// [`Apb`]: super::ClockSource::Apb
         pub fn change_baud(&mut self, baudrate: u32, clock_source: super::ClockSource) {
             self.change_baud_internal(baudrate, clock_source);
             self.txfifo_reset();