Generalize associated interrupt constant through trait

Author: Sh3Rm4n

CHANGELOG.md

@@ -38,7 +38,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
   for configuration purposes. ([#253])
 - Add an associated const to `serial::Instance` to return the corresponding
   `pac::Interrupt`-number, which is useful to `unmask()` interrupts.
-  An `nvic()` function to `Serial` was also added for convinience. ([#253])
+  An `interrupt()` function to `Serial` was also added for convinience. ([#253])
 - Add a `Serial::is_busy()` function to check, if the serial device is busy.
   Useful to block on this function, e.g. `while serial.is_busy() {}`. ([#253])
 - Add `BaudTable` a convinience wrapper around `Baud` to configure the `Serial`

examples/gpio_interrupts.rs

@@ -47,7 +47,7 @@ fn main() -> ! {
     syscfg.select_exti_interrupt_source(&user_button);
     user_button.trigger_on_edge(&mut exti, Edge::Rising);
     user_button.enable_interrupt(&mut exti);
-    let interrupt_num = user_button.nvic(); // hal::pac::Interrupt::EXTI0
+    let interrupt_num = user_button.interrupt(); // hal::pac::Interrupt::EXTI0
 
     // Moving ownership to the global BUTTON so we can clear the interrupt pending bit.
     cortex_m::interrupt::free(|cs| *BUTTON.borrow(cs).borrow_mut() = Some(user_button));

src/gpio.rs

@@ -592,7 +592,7 @@ where
     /// This is also useful for all other [`cortex_m::peripheral::NVIC`] functions.
     // TODO(Sh3rm4n): It would be cool to have this either const or have a const function.
     // But this is currenlty not possible, because index() is runtime defined.
-    pub fn nvic(&self) -> Interrupt {
+    pub fn interrupt(&self) -> Interrupt {
         match self.index.index() {
             0 => Interrupt::EXTI0,
             1 => Interrupt::EXTI1,

src/interrupts.rs

@@ -0,0 +1,16 @@
+//! Common Interrupt interface defintions shared between peipherals.
+
+/// A common interrupt number interface, which returns the associated interrupt
+/// of the peripheral.
+///
+/// Used to unmask / enable the interrupt with [`cortex_m::peripheral::NVIC::unmask()`].
+/// This is useful for all `cortex_m::peripheral::INTERRUPT` functions.
+pub trait InterruptNumber {
+    /// The type used to represent the Interrupt Number.
+    ///
+    /// This type of interrupt should be compatible with [`cortex_m::peripheral::NVIC`].
+    type Interrupt;
+
+    /// The assocaited constant of the interrupt
+    const INTERRUPT: Self::Interrupt;
+}

src/lib.rs

@@ -176,6 +176,7 @@ pub mod dma;
 pub mod flash;
 pub mod gpio;
 pub mod i2c;
+pub mod interrupts;
 pub mod prelude;
 pub mod pwm;
 pub mod rcc;

src/serial.rs

@@ -735,15 +735,15 @@ where
     /// ```
     /// use cortex_m::peripheral::INTERRUPT;
     /// use stm32f3xx_hal::pac::USART1;
-    /// use stm32f3xx_hal::serial::Instance;
+    /// use stm32f3xx_hal::interrupt::InterruptNumber;
     ///
-    /// const interrupt: INTERRUPT = <USART1 as Instance>::INTERRUPT;
+    /// const INTERRUPT: Interrupt = <USART1 as InterruptNumber>::INTERRUPT;
     /// ```
     ///
     /// though this function can not be used in a const context.
     #[doc(alias = "unmask")]
-    pub fn nvic(&self) -> Interrupt {
-        <Usart as Instance>::INTERRUPT
+    pub fn interrupt(&self) -> <Usart as crate::interrupts::InterruptNumber>::Interrupt {
+        <Usart as crate::interrupts::InterruptNumber>::INTERRUPT
     }
 
     /// Enable the interrupt for the specified [`Event`].
@@ -1291,14 +1291,12 @@ impl ReceiverTimeoutExt for USART2 {}
 impl ReceiverTimeoutExt for USART3 {}
 
 /// UART instance
-pub trait Instance: Deref<Target = RegisterBlock> + crate::private::Sealed {
+pub trait Instance:
+    Deref<Target = RegisterBlock> + crate::interrupts::InterruptNumber + crate::private::Sealed
+{
     /// Peripheral bus instance which is responsible for the peripheral
     type APB;
 
-    /// The associated interrupt number, used to unmask / enable the interrupt
-    /// with [`cortex_m::peripheral::NVIC::unmask()`]
-    const INTERRUPT: Interrupt;
-
     #[doc(hidden)]
     fn enable_clock(apb1: &mut Self::APB);
     #[doc(hidden)]
@@ -1321,9 +1319,13 @@ macro_rules! usart {
     ) => {
         $(
             impl crate::private::Sealed for $USARTX {}
+            impl crate::interrupts::InterruptNumber for $USARTX {
+                type Interrupt = Interrupt;
+                const INTERRUPT: Interrupt = $INTERRUPT;
+            }
+
             impl Instance for $USARTX {
                 type APB = $APB;
-                const INTERRUPT: Interrupt = $INTERRUPT;
                 fn enable_clock(apb: &mut Self::APB) {
                     apb.enr().modify(|_, w| w.$usartXen().enabled());
                     apb.rstr().modify(|_, w| w.$usartXrst().reset());

src/timer.rs

@@ -18,7 +18,7 @@ use crate::pac::RCC;
 use crate::rcc::{Clocks, APB1, APB2};
 use crate::time::{duration, fixed_point::FixedPoint, rate::Hertz};
 
-pub mod interrupts;
+mod interrupts;
 
 /// A monotonic nondecreasing timer.
 #[derive(Debug, Clone, Copy)]
@@ -146,8 +146,9 @@ where
     /// ```
     ///
     /// though this function can not be used in a const context.
-    pub fn nvic(&self) -> <TIM as self::interrupts::InterruptNumber>::Interrupt {
-        <TIM as self::interrupts::InterruptNumber>::INTERRUPT
+    #[doc(alias = "unmask")]
+    pub fn interrupt(&self) -> <TIM as crate::interrupts::InterruptNumber>::Interrupt {
+        <TIM as crate::interrupts::InterruptNumber>::INTERRUPT
     }
 
     /// Enable or disable the interrupt for the specified [`Event`].
@@ -324,7 +325,7 @@ pub trait CommonRegisterBlock: crate::private::Sealed {
 
 /// Associated clocks with timers
 pub trait Instance:
-    CommonRegisterBlock + self::interrupts::InterruptNumber + crate::private::Sealed
+    CommonRegisterBlock + crate::interrupts::InterruptNumber + crate::private::Sealed
 {
     /// Peripheral bus instance which is responsible for the peripheral
     type APB;

src/timer/interrupts.rs

@@ -2,11 +2,8 @@ use crate::pac::Interrupt;
 
 /// Wrapper around interrupt types for the timers.
 #[derive(Copy, Clone, Debug)]
-// FIXME: Interrupt is not formattable?
-// #[cfg_attr(feature = "defmt", derive(defmt::Format))]
-// TODO: Does it make sense to introduce an enum for that?
-// enum ItrTypes {Global, Break, Update, Trigger, CaptureCompare}
-#[non_exhaustive] // To make the type non-creatable but still accessable.
+// To make the type non-creatable but still accessable.
+#[non_exhaustive]
 pub struct InterruptTypes {
     /// Break Interrupt
     r#break: Interrupt,
@@ -18,16 +15,6 @@ pub struct InterruptTypes {
     capture_compare: Interrupt,
 }
 
-// FIXME: This super-trait constrained makes it difficult to use this trait
-// without cfg(feature...)
-// pub trait InterruptNumber: crate::private::Sealed {
-// TODO: Rename, because in conflict with: use cortex_m::interrupt::InterruptNumber;
-pub trait InterruptNumber {
-    type Interrupt;
-    const INTERRUPT: Self::Interrupt;
-    fn nvic() -> Self::Interrupt;
-}
-
 // FIXME: Use conditional feature compilation to make this compialble for all chip families.
 // TODO: Check if pub is needed.
 pub(crate) const TIM2: Interrupt = Interrupt::TIM2;
@@ -112,12 +99,9 @@ macro_rules! single {
     ([ $($X:literal),+ ]) => {
         paste::paste! {
             $(
-                impl InterruptNumber for crate::pac::[<TIM $X>] {
+                impl crate::interrupts::InterruptNumber for crate::pac::[<TIM $X>] {
                     type Interrupt = crate::timer::interrupts::Interrupt;
                     const INTERRUPT: Self::Interrupt = crate::timer::interrupts::[<TIM $X>];
-                    fn nvic() -> Self::Interrupt {
-                        [<TIM $X>]
-                    }
                 }
             )+
         }
@@ -128,12 +112,9 @@ macro_rules! multi {
     ([ $($X:literal),+ ]) => {
         paste::paste! {
             $(
-                impl InterruptNumber for crate::pac::[<TIM $X>] {
+                impl crate::interrupts::InterruptNumber for crate::pac::[<TIM $X>] {
                     type Interrupt = crate::timer::interrupts::InterruptTypes;
                     const INTERRUPT: Self::Interrupt = crate::timer::interrupts::[<TIM $X _TYPES>];
-                    fn nvic() -> Self::Interrupt {
-                        [<TIM $X _TYPES>]
-                    }
                 }
             )+
         }

testsuite/tests/timer.rs

@@ -8,8 +8,9 @@ use panic_probe as _;
 
 use stm32f3xx_hal as hal;
 
+use hal::interrupts::InterruptNumber;
 use hal::rcc::{Clocks, APB1};
-use hal::timer::{self, Event, MonoTimer, Timer};
+use hal::timer::{Event, MonoTimer, Timer};
 use hal::{interrupt, pac, prelude::*};
 
 use pac::TIM2;
@@ -44,7 +45,7 @@ mod tests {
 
         assert!(mono_timer.frequency() == clocks.hclk());
 
-        unsafe { cortex_m::peripheral::NVIC::unmask(timer.nvic()) };
+        unsafe { cortex_m::peripheral::NVIC::unmask(timer.interrupt()) };
 
         State {
             timer: Some(timer),
@@ -123,7 +124,7 @@ fn TIM2() {
     //
     // This is all needed, to clear the fired interrupt.
     assert!(cortex_m::peripheral::NVIC::is_active(
-        <pac::TIM2 as timer::interrupts::InterruptNumber>::INTERRUPT
+        <pac::TIM2 as InterruptNumber>::INTERRUPT
     ));
-    cortex_m::peripheral::NVIC::mask(<pac::TIM2 as timer::interrupts::InterruptNumber>::INTERRUPT);
+    cortex_m::peripheral::NVIC::mask(<pac::TIM2 as InterruptNumber>::INTERRUPT);
 }

testsuite/tests/uart.rs

@@ -8,6 +8,7 @@ use enumset::EnumSet;
 use stm32f3xx_hal as hal;
 
 use hal::gpio::{OpenDrain, PushPull, AF7};
+use hal::interrupts::InterruptNumber;
 use hal::pac;
 use hal::prelude::*;
 use hal::serial::{
@@ -86,10 +87,10 @@ fn trigger_event<Usart, Pins>(
     assert!(!serial.triggered_events().contains(event));
     // TODO: Is that true?: Unpend any pending interrupts - more than one could be pending,
     // because of the late clearing of the interrupt
-    cortex_m::peripheral::NVIC::unpend(<pac::USART1 as Instance>::INTERRUPT);
+    cortex_m::peripheral::NVIC::unpend(<pac::USART1 as InterruptNumber>::INTERRUPT);
     // Now unmask all interrupts again, which where masks in the iterrupt rountine,
     // as a measurement to disable all interrupts.
-    unsafe { cortex_m::peripheral::NVIC::unmask(<pac::USART1 as Instance>::INTERRUPT) }
+    unsafe { cortex_m::peripheral::NVIC::unmask(<pac::USART1 as InterruptNumber>::INTERRUPT) }
     // Clear the interrupt flag again. And make double sure, that no interrupt
     // fired again.
     INTERRUPT_FIRED.store(false, Ordering::SeqCst);
@@ -150,7 +151,7 @@ mod tests {
             &mut rcc.apb2,
         );
 
-        unsafe { cortex_m::peripheral::NVIC::unmask(serial1.nvic()) }
+        unsafe { cortex_m::peripheral::NVIC::unmask(serial1.interrupt()) }
 
         super::State {
             serial1: Some(serial1),
@@ -453,7 +454,7 @@ fn USART1_EXTI25() {
     //
     // This is all needed, to clear the fired interrupt.
     assert!(cortex_m::peripheral::NVIC::is_active(
-        <pac::USART1 as Instance>::INTERRUPT
+        <pac::USART1 as InterruptNumber>::INTERRUPT
     ));
-    cortex_m::peripheral::NVIC::mask(<pac::USART1 as Instance>::INTERRUPT);
+    cortex_m::peripheral::NVIC::mask(<pac::USART1 as InterruptNumber>::INTERRUPT);
 }