Use #[instability::unstable] where possible, cleanup and improve consistency

documentation/DEVELOPER-GUIDELINES.md

@@ -98,6 +98,9 @@ In general, the [Rust API Guidelines](https://rust-lang.github.io/api-guidelines
 - Generally, follow common "good practices" and idiomatic Rust style
 - All `Future` objects (public or private) must be marked with ``#[must_use = "futures do nothing unless you `.await` or poll them"]``.
 - Prefer `cfg_if!` (or, if the branches just pick between separate values of the same variable, `cfg!()`) over multiple exclusive `#[cfg]` attributes. `cfg_if!`/`cfg!()` visually divide the options, often results in simpler conditions and simplifies adding new branches in the future.
+- When marking an API as `unstable`:
+  - Prefer to use `#[instability::unstable]`.
+  - Use the attribute on each public function instead of inherent impl blocks.
 
 ## Driver implementation
 

esp-hal/src/assist_debug.rs

@@ -24,7 +24,7 @@
 //! - This driver has only blocking API
 
 use crate::{
-    interrupt::{InterruptConfigurable, InterruptHandler},
+    interrupt::InterruptHandler,
     pac,
     peripheral::{Peripheral, PeripheralRef},
     peripherals::{Interrupt, ASSIST_DEBUG},
@@ -46,15 +46,12 @@ impl<'d> DebugAssist<'d> {
         DebugAssist { debug_assist }
     }
 
-    fn regs(&self) -> &pac::assist_debug::RegisterBlock {
-        self.debug_assist.register_block()
-    }
-}
-
-impl crate::private::Sealed for DebugAssist<'_> {}
-
-impl InterruptConfigurable for DebugAssist<'_> {
-    fn set_interrupt_handler(&mut self, handler: InterruptHandler) {
+    /// Register an interrupt handler for the Debug Assist module.
+    ///
+    /// Note that this will replace any previously registered interrupt
+    /// handlers.
+    #[instability::unstable]
+    pub fn set_interrupt_handler(&mut self, handler: InterruptHandler) {
         for core in crate::Cpu::other() {
             crate::interrupt::disable(core, Interrupt::ASSIST_DEBUG);
         }
@@ -64,6 +61,19 @@ impl InterruptConfigurable for DebugAssist<'_> {
             handler.priority()
         ));
     }
+
+    fn regs(&self) -> &pac::assist_debug::RegisterBlock {
+        self.debug_assist.register_block()
+    }
+}
+
+impl crate::private::Sealed for DebugAssist<'_> {}
+
+#[instability::unstable]
+impl crate::interrupt::InterruptConfigurable for DebugAssist<'_> {
+    fn set_interrupt_handler(&mut self, handler: InterruptHandler) {
+        self.set_interrupt_handler(handler);
+    }
 }
 
 #[cfg(assist_debug_sp_monitor)]

esp-hal/src/dma/mod.rs

@@ -2496,6 +2496,7 @@ where
     /// Sets the interrupt handler for RX and TX interrupts.
     ///
     /// Interrupts are not enabled at the peripheral level here.
+    #[instability::unstable]
     pub fn set_interrupt_handler(&mut self, handler: InterruptHandler) {
         self.rx.set_interrupt_handler(handler);
         self.tx.set_interrupt_handler(handler);

esp-hal/src/ecc.rs

@@ -28,7 +28,7 @@
 use core::marker::PhantomData;
 
 use crate::{
-    interrupt::{InterruptConfigurable, InterruptHandler},
+    interrupt::InterruptHandler,
     pac,
     peripheral::{Peripheral, PeripheralRef},
     peripherals::{Interrupt, ECC},
@@ -118,13 +118,10 @@ impl<'d> Ecc<'d, Blocking> {
 
 impl crate::private::Sealed for Ecc<'_, Blocking> {}
 
-impl InterruptConfigurable for Ecc<'_, Blocking> {
+#[instability::unstable]
+impl crate::interrupt::InterruptConfigurable for Ecc<'_, Blocking> {
     fn set_interrupt_handler(&mut self, handler: InterruptHandler) {
-        for core in crate::Cpu::other() {
-            crate::interrupt::disable(core, Interrupt::ECC);
-        }
-        unsafe { crate::interrupt::bind_interrupt(Interrupt::ECC, handler.handler()) };
-        unwrap!(crate::interrupt::enable(Interrupt::ECC, handler.priority()));
+        self.set_interrupt_handler(handler);
     }
 }
 
@@ -989,6 +986,19 @@ impl<Dm: DriverMode> Ecc<'_, Dm> {
         Ok(())
     }
 
+    /// Register an interrupt handler for the ECC peripheral.
+    ///
+    /// Note that this will replace any previously registered interrupt
+    /// handlers.
+    #[instability::unstable]
+    pub fn set_interrupt_handler(&mut self, handler: InterruptHandler) {
+        for core in crate::Cpu::other() {
+            crate::interrupt::disable(core, Interrupt::ECC);
+        }
+        unsafe { crate::interrupt::bind_interrupt(Interrupt::ECC, handler.handler()) };
+        unwrap!(crate::interrupt::enable(Interrupt::ECC, handler.priority()));
+    }
+
     fn is_busy(&self) -> bool {
         self.regs().mult_conf().read().start().bit_is_set()
     }

esp-hal/src/gpio/mod.rs

@@ -56,8 +56,6 @@ use portable_atomic::{AtomicU32, Ordering};
 use procmacros::ram;
 use strum::EnumCount;
 
-#[cfg(feature = "unstable")]
-use crate::interrupt::InterruptConfigurable;
 #[cfg(any(lp_io, rtc_cntl))]
 use crate::peripherals::gpio::{handle_rtcio, handle_rtcio_with_resistors};
 pub use crate::soc::gpio::*;
@@ -789,7 +787,7 @@ impl Io {
 impl crate::private::Sealed for Io {}
 
 #[instability::unstable]
-impl InterruptConfigurable for Io {
+impl crate::interrupt::InterruptConfigurable for Io {
     fn set_interrupt_handler(&mut self, handler: InterruptHandler) {
         self.set_interrupt_handler(handler);
     }

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

@@ -27,8 +27,6 @@ use core::{
     task::{Context, Poll},
 };
 
-#[cfg(any(doc, feature = "unstable"))]
-use embassy_embedded_hal::SetConfig;
 use embedded_hal::i2c::Operation as EhalOperation;
 use enumset::{EnumSet, EnumSetType};
 use fugit::HertzU32;
@@ -43,7 +41,7 @@ use crate::{
         PinGuard,
         Pull,
     },
-    interrupt::{InterruptConfigurable, InterruptHandler},
+    interrupt::InterruptHandler,
     pac::i2c0::{RegisterBlock, COMD},
     peripheral::{Peripheral, PeripheralRef},
     peripherals::Interrupt,
@@ -449,9 +447,8 @@ pub struct I2c<'d, Dm: DriverMode> {
     scl_pin: PinGuard,
 }
 
-#[cfg(any(doc, feature = "unstable"))]
-#[cfg_attr(docsrs, doc(cfg(feature = "unstable")))]
-impl<Dm: DriverMode> SetConfig for I2c<'_, Dm> {
+#[instability::unstable]
+impl<Dm: DriverMode> embassy_embedded_hal::SetConfig for I2c<'_, Dm> {
     type Config = Config;
     type ConfigError = ConfigError;
 
@@ -828,7 +825,8 @@ impl<'d> I2c<'d, Blocking> {
 
 impl private::Sealed for I2c<'_, Blocking> {}
 
-impl InterruptConfigurable for I2c<'_, Blocking> {
+#[instability::unstable]
+impl crate::interrupt::InterruptConfigurable for I2c<'_, Blocking> {
     fn set_interrupt_handler(&mut self, handler: InterruptHandler) {
         self.i2c.info().set_interrupt_handler(handler);
     }

esp-hal/src/interrupt/software.rs

@@ -56,6 +56,7 @@ pub struct SoftwareInterrupt<const NUM: u8>;
 
 impl<const NUM: u8> SoftwareInterrupt<NUM> {
     /// Sets the interrupt handler for this software-interrupt
+    #[instability::unstable]
     pub fn set_interrupt_handler(&mut self, handler: InterruptHandler) {
         let interrupt = match NUM {
             0 => crate::peripherals::Interrupt::FROM_CPU_INTR0,

esp-hal/src/lcd_cam/mod.rs

@@ -13,7 +13,7 @@ use core::marker::PhantomData;
 use crate::{
     asynch::AtomicWaker,
     handler,
-    interrupt::{InterruptConfigurable, InterruptHandler},
+    interrupt::InterruptHandler,
     lcd_cam::{cam::Cam, lcd::Lcd},
     peripheral::Peripheral,
     peripherals::{Interrupt, LCD_CAM},
@@ -64,13 +64,13 @@ impl<'d> LcdCam<'d, Blocking> {
             cam: self.cam,
         }
     }
-}
 
-impl crate::private::Sealed for LcdCam<'_, Blocking> {}
-// TODO: This interrupt is shared with the Camera module, we should handle this
-// in a similar way to the gpio::IO
-impl InterruptConfigurable for LcdCam<'_, Blocking> {
-    fn set_interrupt_handler(&mut self, handler: InterruptHandler) {
+    /// Registers an interrupt handler for the LCD_CAM peripheral.
+    ///
+    /// Note that this will replace any previously registered interrupt
+    /// handlers.
+    #[instability::unstable]
+    pub fn set_interrupt_handler(&mut self, handler: InterruptHandler) {
         for core in crate::Cpu::other() {
             crate::interrupt::disable(core, Interrupt::LCD_CAM);
         }
@@ -82,6 +82,16 @@ impl InterruptConfigurable for LcdCam<'_, Blocking> {
     }
 }
 
+impl crate::private::Sealed for LcdCam<'_, Blocking> {}
+// TODO: This interrupt is shared with the Camera module, we should handle this
+// in a similar way to the gpio::IO
+#[instability::unstable]
+impl crate::interrupt::InterruptConfigurable for LcdCam<'_, Blocking> {
+    fn set_interrupt_handler(&mut self, handler: InterruptHandler) {
+        self.set_interrupt_handler(handler);
+    }
+}
+
 impl<'d> LcdCam<'d, Async> {
     /// Reconfigures the peripheral for blocking operation.
     pub fn into_blocking(self) -> LcdCam<'d, Blocking> {

esp-hal/src/parl_io.rs

@@ -152,7 +152,7 @@ use crate::{
         interconnect::{InputConnection, OutputConnection, PeripheralInput, PeripheralOutput},
         NoPin,
     },
-    interrupt::{InterruptConfigurable, InterruptHandler},
+    interrupt::InterruptHandler,
     peripheral::{self, Peripheral},
     peripherals::{Interrupt, PARL_IO, PCR},
     system::{self, GenericPeripheralGuard},
@@ -1162,6 +1162,7 @@ impl<'d> ParlIoFullDuplex<'d, Blocking> {
     /// [crate::interrupt::Priority::min()]
     ///
     /// Interrupts are not enabled at the peripheral level here.
+    #[instability::unstable]
     pub fn set_interrupt_handler(&mut self, handler: InterruptHandler) {
         internal_set_interrupt_handler(handler);
     }
@@ -1189,7 +1190,8 @@ impl<'d> ParlIoFullDuplex<'d, Blocking> {
 
 impl crate::private::Sealed for ParlIoFullDuplex<'_, Blocking> {}
 
-impl InterruptConfigurable for ParlIoFullDuplex<'_, Blocking> {
+#[instability::unstable]
+impl crate::interrupt::InterruptConfigurable for ParlIoFullDuplex<'_, Blocking> {
     fn set_interrupt_handler(&mut self, handler: crate::interrupt::InterruptHandler) {
         ParlIoFullDuplex::set_interrupt_handler(self, handler);
     }
@@ -1273,6 +1275,7 @@ impl<'d> ParlIoTxOnly<'d, Blocking> {
     /// [crate::interrupt::Priority::min()]
     ///
     /// Interrupts are not enabled at the peripheral level here.
+    #[instability::unstable]
     pub fn set_interrupt_handler(&mut self, handler: InterruptHandler) {
         internal_set_interrupt_handler(handler);
     }
@@ -1313,7 +1316,8 @@ impl<'d> ParlIoTxOnly<'d, Async> {
 
 impl crate::private::Sealed for ParlIoTxOnly<'_, Blocking> {}
 
-impl InterruptConfigurable for ParlIoTxOnly<'_, Blocking> {
+#[instability::unstable]
+impl crate::interrupt::InterruptConfigurable for ParlIoTxOnly<'_, Blocking> {
     fn set_interrupt_handler(&mut self, handler: crate::interrupt::InterruptHandler) {
         ParlIoTxOnly::set_interrupt_handler(self, handler);
     }
@@ -1380,6 +1384,7 @@ impl<'d> ParlIoRxOnly<'d, Blocking> {
     /// [crate::interrupt::Priority::min()]
     ///
     /// Interrupts are not enabled at the peripheral level here.
+    #[instability::unstable]
     pub fn set_interrupt_handler(&mut self, handler: InterruptHandler) {
         internal_set_interrupt_handler(handler);
     }
@@ -1420,7 +1425,8 @@ impl<'d> ParlIoRxOnly<'d, Async> {
 
 impl crate::private::Sealed for ParlIoRxOnly<'_, Blocking> {}
 
-impl InterruptConfigurable for ParlIoRxOnly<'_, Blocking> {
+#[instability::unstable]
+impl crate::interrupt::InterruptConfigurable for ParlIoRxOnly<'_, Blocking> {
     fn set_interrupt_handler(&mut self, handler: crate::interrupt::InterruptHandler) {
         ParlIoRxOnly::set_interrupt_handler(self, handler);
     }

esp-hal/src/pcnt/mod.rs

@@ -97,7 +97,7 @@
 
 use self::unit::Unit;
 use crate::{
-    interrupt::{self, InterruptConfigurable, InterruptHandler},
+    interrupt::{self, InterruptHandler},
     peripheral::{Peripheral, PeripheralRef},
     peripherals::{Interrupt, PCNT},
     system::GenericPeripheralGuard,
@@ -181,16 +181,26 @@ impl<'d> Pcnt<'d> {
             _guard: guard,
         }
     }
-}
-
-impl crate::private::Sealed for Pcnt<'_> {}
 
-impl InterruptConfigurable for Pcnt<'_> {
-    fn set_interrupt_handler(&mut self, handler: InterruptHandler) {
+    /// Set the interrupt handler for the PCNT peripheral.
+    ///
+    /// Note that this will replace any previously registered interrupt
+    /// handlers.
+    #[instability::unstable]
+    pub fn set_interrupt_handler(&mut self, handler: InterruptHandler) {
         for core in crate::Cpu::other() {
             crate::interrupt::disable(core, Interrupt::PCNT);
         }
         unsafe { interrupt::bind_interrupt(Interrupt::PCNT, handler.handler()) };
         unwrap!(interrupt::enable(Interrupt::PCNT, handler.priority()));
     }
 }
+
+impl crate::private::Sealed for Pcnt<'_> {}
+
+#[instability::unstable]
+impl crate::interrupt::InterruptConfigurable for Pcnt<'_> {
+    fn set_interrupt_handler(&mut self, handler: InterruptHandler) {
+        self.set_interrupt_handler(handler);
+    }
+}

esp-hal/src/rmt.rs

@@ -236,7 +236,6 @@ use crate::{
         Level,
     },
     handler,
-    interrupt::InterruptConfigurable,
     peripheral::Peripheral,
     peripherals::{Interrupt, RMT},
     soc::constants,
@@ -446,12 +445,13 @@ impl<'d> Rmt<'d, Blocking> {
         self.set_interrupt_handler(async_interrupt_handler);
         Rmt::create(self.peripheral)
     }
-}
-
-impl crate::private::Sealed for Rmt<'_, Blocking> {}
 
-impl InterruptConfigurable for Rmt<'_, Blocking> {
-    fn set_interrupt_handler(&mut self, handler: crate::interrupt::InterruptHandler) {
+    /// Registers an interrupt handler for the RMT peripheral.
+    ///
+    /// Note that this will replace any previously registered interrupt
+    /// handlers.
+    #[instability::unstable]
+    pub fn set_interrupt_handler(&mut self, handler: crate::interrupt::InterruptHandler) {
         for core in crate::Cpu::other() {
             crate::interrupt::disable(core, Interrupt::RMT);
         }
@@ -460,6 +460,15 @@ impl InterruptConfigurable for Rmt<'_, Blocking> {
     }
 }
 
+impl crate::private::Sealed for Rmt<'_, Blocking> {}
+
+#[instability::unstable]
+impl crate::interrupt::InterruptConfigurable for Rmt<'_, Blocking> {
+    fn set_interrupt_handler(&mut self, handler: crate::interrupt::InterruptHandler) {
+        self.set_interrupt_handler(handler);
+    }
+}
+
 fn configure_rx_channel<'d, P: PeripheralInput, T: RxChannelInternal>(
     pin: impl Peripheral<P = P> + 'd,
     config: RxChannelConfig,