Merge pull request #4922 from WillaWillNot/anybinding_and_bindable_exti

Bindable EXTI interrupts, and removal of AnyChannel support for ExtiInput

Author: xoviat

.vscode/settings.json

@@ -61,4 +61,8 @@
     // "examples/stm32wl/Cargo.toml",
     // "examples/wasm/Cargo.toml",
   ],
-}
+  "rust-analyzer.rustfmt.extraArgs": [
+    //Uncomment to run rustfmt with nightly-only settings that match the CI
+    // "+nightly"
+  ],
+}

docs/examples/layer-by-layer/blinky-async/src/main.rs

@@ -2,15 +2,21 @@
 #![no_main]
 
 use embassy_executor::Spawner;
-use embassy_stm32::exti::ExtiInput;
+use embassy_stm32::exti::{self, ExtiInput};
 use embassy_stm32::gpio::{Level, Output, Pull, Speed};
+use embassy_stm32::{bind_interrupts, interrupt};
 use {defmt_rtt as _, panic_probe as _};
 
+bind_interrupts!(
+    pub struct Irqs{
+        EXTI15_10  => exti::InterruptHandler<interrupt::typelevel::EXTI15_10 >;
+});
+
 #[embassy_executor::main]
 async fn main(_spawner: Spawner) {
     let p = embassy_stm32::init(Default::default());
     let mut led = Output::new(p.PB14, Level::Low, Speed::VeryHigh);
-    let mut button = ExtiInput::new(p.PC13, p.EXTI13, Pull::Up);
+    let mut button = ExtiInput::new(p.PC13, p.EXTI13, Pull::Up, Irqs);
 
     loop {
         button.wait_for_any_edge().await;

docs/pages/faq.adoc

@@ -171,7 +171,11 @@ Note that the git revision should match any other embassy patches or git depende
 
 == Can I use manual ISRs alongside Embassy?
 
-Yes! This can be useful if you need to respond to an event as fast as possible, and the latency caused by the usual “ISR, wake, return from ISR, context switch to woken task” flow is too much for your application. Simply define a `#[interrupt] fn INTERRUPT_NAME() {}` handler as you would link:https://docs.rust-embedded.org/book/start/interrupts.html[in any other embedded rust project].
+Yes! This can be useful if you need to respond to an event as fast as possible, and the latency caused by the usual “ISR, wake, return from ISR, context switch to woken task” flow is too much for your application. 
+
+You may simply define a `#[interrupt] fn INTERRUPT_NAME() {}` handler as you would link:https://docs.rust-embedded.org/book/start/interrupts.html[in any other embedded rust project].
+
+Or you may define a struct implementing the `embassy-[family]::interrupt::typelevel::Handler` trait with an on_interrupt() method, and bind it to the interrupt vector via the `bind_interrupts!` macro, which introduces only a single indirection. This allows the mixing of manual ISRs with Embassy driver-defined ISRs; handlers will be called directly in the order they appear in the macro.
 
 == How can I measure resource usage (CPU, RAM, etc.)?
 

docs/pages/layer_by_layer.adoc

@@ -76,7 +76,7 @@ The async version looks very similar to the HAL version, apart from a few minor
 * The peripheral initialization is done by the main macro, and is handed to the main task.
 * Before checking the button state, the application is awaiting a transition in the pin state (low -> high or high -> low).
 
-When `button.wait_for_any_edge().await` is called, the executor will pause the main task and put the microcontroller in sleep mode, unless there are other tasks that can run. Internally, the Embassy HAL has configured the interrupt handler for the button (in `ExtiInput`), so that whenever an interrupt is raised, the task awaiting the button will be woken up.
+When `button.wait_for_any_edge().await` is called, the executor will pause the main task and put the microcontroller in sleep mode, unless there are other tasks that can run. On this chip, interrupt signals on EXTI lines 10-15 (including the button on EXTI line 13) raise the hardware interrupt EXTI15_10. This interrupt handler has been bound (using `bind_interrupts!`) to call the `InterruptHandler` provided by the exti module, so that whenever an interrupt is raised, the task awaiting the button via `wait_for_any_edge()` will be woken up.
 
 The minimal overhead of the executor and the ability to run multiple tasks "concurrently" combined with the enormous simplification of the application, makes `async` a great fit for embedded.
 

embassy-stm32/CHANGELOG.md

@@ -75,6 +75,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - fix: fixing channel numbers on vbat and vddcore for adc on adc
 - adc: adding disable to vbat
 - feat: stm32/flash: add async support for h7 family
+- feat: exti brought in line with other drivers' interrupt rebinding system ([#4922](https://github.com/embassy-rs/embassy/pull/4922))
+- removal: ExtiInput no longer accepts AnyPin/AnyChannel; AnyChannel removed entirely
+- fix: build script ensures EXTI2_TSC is listed as the IRQ of EXTI2 even if the PAC doesn't
 - feat: stm32/lcd: added implementation
 
 ## 0.4.0 - 2025-08-26

embassy-stm32/build.rs

@@ -353,8 +353,13 @@ fn main() {
     // ========
     // Generate interrupt declarations
 
+    let mut exti2_tsc_shared_int_present: Option<stm32_metapac::metadata::Interrupt> = None;
     let mut irqs = Vec::new();
     for irq in METADATA.interrupts {
+        // The PAC doesn't ensure this is listed as the IRQ of EXTI2, so we must do so
+        if irq.name == "EXTI2_TSC" {
+            exti2_tsc_shared_int_present = Some(irq.clone())
+        }
         irqs.push(format_ident!("{}", irq.name));
     }
 
@@ -1812,7 +1817,19 @@ fn main() {
     for p in METADATA.peripherals {
         let mut pt = TokenStream::new();
 
+        let mut exti2_tsc_injected = false;
+        if let Some(ref irq) = exti2_tsc_shared_int_present
+            && p.name == "EXTI"
+        {
+            exti2_tsc_injected = true;
+            let iname = format_ident!("{}", irq.name);
+            let sname = format_ident!("{}", "EXTI2");
+            pt.extend(quote!(pub type #sname = crate::interrupt::typelevel::#iname;));
+        }
         for irq in p.interrupts {
+            if exti2_tsc_injected && irq.signal == "EXTI2" {
+                continue;
+            }
             let iname = format_ident!("{}", irq.interrupt);
             let sname = format_ident!("{}", irq.signal);
             pt.extend(quote!(pub type #sname = crate::interrupt::typelevel::#iname;));

embassy-stm32/src/exti.rs

@@ -5,14 +5,16 @@ use core::marker::PhantomData;
 use core::pin::Pin;
 use core::task::{Context, Poll};
 
-use embassy_hal_internal::{PeripheralType, impl_peripheral};
+use embassy_hal_internal::PeripheralType;
 use embassy_sync::waitqueue::AtomicWaker;
 use futures_util::FutureExt;
 
-use crate::gpio::{AnyPin, Input, Level, Pin as GpioPin, PinNumber, Pull};
+use crate::gpio::{AnyPin, ExtiPin, Input, Level, Pin as GpioPin, PinNumber, Pull};
+use crate::interrupt::Interrupt as InterruptEnum;
+use crate::interrupt::typelevel::{Binding, Handler, Interrupt as InterruptType};
 use crate::pac::EXTI;
 use crate::pac::exti::regs::Lines;
-use crate::{Peri, interrupt, pac, peripherals};
+use crate::{Peri, pac};
 
 const EXTI_COUNT: usize = 16;
 static EXTI_WAKERS: [AtomicWaker; EXTI_COUNT] = [const { AtomicWaker::new() }; EXTI_COUNT];
@@ -106,10 +108,17 @@ impl<'d> Unpin for ExtiInput<'d> {}
 
 impl<'d> ExtiInput<'d> {
     /// Create an EXTI input.
-    pub fn new<T: GpioPin>(pin: Peri<'d, T>, ch: Peri<'d, T::ExtiChannel>, pull: Pull) -> Self {
-        // Needed if using AnyPin+AnyChannel.
-        assert_eq!(pin.pin(), ch.number());
-
+    ///
+    /// The Binding must bind the Channel's IRQ to [InterruptHandler].
+    pub fn new<T: ExtiPin + GpioPin>(
+        pin: Peri<'d, T>,
+        _ch: Peri<'d, T::ExtiChannel>,
+        pull: Pull,
+        _irq: impl Binding<
+            <<T as ExtiPin>::ExtiChannel as Channel>::IRQ,
+            InterruptHandler<<<T as ExtiPin>::ExtiChannel as Channel>::IRQ>,
+        >,
+    ) -> Self {
         Self {
             pin: Input::new(pin, pull),
         }
@@ -328,7 +337,7 @@ macro_rules! foreach_exti_irq {
             (EXTI15) => { $action!(EXTI15); };
 
             // plus the weird ones
-            (EXTI0_1)   => { $action!( EXTI0_1 ); };
+            (EXTI0_1)   => { $action!(EXTI0_1); };
             (EXTI15_10) => { $action!(EXTI15_10); };
             (EXTI15_4)  => { $action!(EXTI15_4); };
             (EXTI1_0)   => { $action!(EXTI1_0); };
@@ -341,57 +350,67 @@ macro_rules! foreach_exti_irq {
     };
 }
 
-macro_rules! impl_irq {
-    ($e:ident) => {
-        #[allow(non_snake_case)]
-        #[cfg(feature = "rt")]
-        #[interrupt]
-        unsafe fn $e() {
-            on_irq()
-        }
-    };
+///EXTI interrupt handler. All EXTI interrupt vectors should be bound to this handler.
+///
+/// It is generic over the [Interrupt](InterruptType) rather
+/// than the [Channel] because it should not be bound multiple
+/// times to the same vector on chips which multiplex multiple EXTI interrupts into one vector.
+//
+// It technically doesn't need to be generic at all, except to satisfy the generic argument
+// of [Handler]. All EXTI interrupts eventually land in the same on_irq() function.
+pub struct InterruptHandler<T: crate::interrupt::typelevel::Interrupt> {
+    _phantom: PhantomData<T>,
 }
 
-foreach_exti_irq!(impl_irq);
+impl<T: InterruptType> Handler<T> for InterruptHandler<T> {
+    unsafe fn on_interrupt() {
+        on_irq()
+    }
+}
 
 trait SealedChannel {}
 
 /// EXTI channel trait.
 #[allow(private_bounds)]
 pub trait Channel: PeripheralType + SealedChannel + Sized {
-    /// Get the EXTI channel number.
+    /// EXTI channel number.
     fn number(&self) -> PinNumber;
+    /// [Enum-level Interrupt](InterruptEnum), which may be the same for multiple channels.
+    fn irq(&self) -> InterruptEnum;
+    /// [Type-level Interrupt](InterruptType), which may be the same for multiple channels.
+    type IRQ: InterruptType;
 }
 
-/// Type-erased EXTI channel.
+//Doc isn't hidden in order to surface the explanation to users, even though it's completely inoperable, not just deprecated.
+//Entire type along with doc can probably be removed after deprecation has appeared in a release once.
+/// Deprecated type-erased EXTI channel.
 ///
-/// This represents ownership over any EXTI channel, known at runtime.
+/// Support for AnyChannel was removed in order to support manually bindable EXTI interrupts via bind_interrupts; [ExtiInput::new()]
+/// must know the required IRQ at compile time, and therefore cannot support type-erased channels.
+#[deprecated = "type-erased EXTI channels are no longer supported, in order to support manually bindable EXTI interrupts (more info: https://github.com/embassy-rs/embassy/pull/4922)"]
 pub struct AnyChannel {
+    #[allow(unused)]
     number: PinNumber,
 }
 
-impl_peripheral!(AnyChannel);
-impl SealedChannel for AnyChannel {}
-impl Channel for AnyChannel {
-    fn number(&self) -> PinNumber {
-        self.number
-    }
-}
-
 macro_rules! impl_exti {
     ($type:ident, $number:expr) => {
-        impl SealedChannel for peripherals::$type {}
-        impl Channel for peripherals::$type {
+        impl SealedChannel for crate::peripherals::$type {}
+        impl Channel for crate::peripherals::$type {
             fn number(&self) -> PinNumber {
                 $number
             }
+            fn irq(&self) -> InterruptEnum {
+                crate::_generated::peripheral_interrupts::EXTI::$type::IRQ
+            }
+            type IRQ = crate::_generated::peripheral_interrupts::EXTI::$type;
         }
 
-        impl From<peripherals::$type> for AnyChannel {
-            fn from(val: peripherals::$type) -> Self {
-                Self {
-                    number: val.number() as PinNumber,
-                }
+        //Still here to surface deprecation messages to the user - remove when removing AnyChannel
+        #[allow(deprecated)]
+        impl From<crate::peripherals::$type> for AnyChannel {
+            fn from(_val: crate::peripherals::$type) -> Self {
+                Self { number: $number }
             }
         }
     };

embassy-stm32/src/gpio.rs

@@ -812,15 +812,19 @@ pub type PinNumber = u8;
 #[cfg(stm32n6)]
 pub type PinNumber = u16;
 
-/// GPIO pin trait.
+/// Pin that can be used to configure an [ExtiInput](crate::exti::ExtiInput). This trait is lost when converting to [AnyPin].
+#[cfg(feature = "exti")]
 #[allow(private_bounds)]
-pub trait Pin: PeripheralType + Into<AnyPin> + SealedPin + Sized + 'static {
+pub trait ExtiPin: PeripheralType + SealedPin {
     /// EXTI channel assigned to this pin.
     ///
     /// For example, PC4 uses EXTI4.
-    #[cfg(feature = "exti")]
     type ExtiChannel: crate::exti::Channel;
+}
 
+/// GPIO pin trait.
+#[allow(private_bounds)]
+pub trait Pin: PeripheralType + Into<AnyPin> + SealedPin + Sized + 'static {
     /// Number of the pin within the port (0..31)
     #[inline]
     fn pin(&self) -> PinNumber {
@@ -834,7 +838,7 @@ pub trait Pin: PeripheralType + Into<AnyPin> + SealedPin + Sized + 'static {
     }
 }
 
-/// Type-erased GPIO pin
+/// Type-erased GPIO pin.
 pub struct AnyPin {
     pin_port: PinNumber,
 }
@@ -862,10 +866,7 @@ impl AnyPin {
 }
 
 impl_peripheral!(AnyPin);
-impl Pin for AnyPin {
-    #[cfg(feature = "exti")]
-    type ExtiChannel = crate::exti::AnyChannel;
-}
+impl Pin for AnyPin {}
 impl SealedPin for AnyPin {
     #[inline]
     fn pin_port(&self) -> PinNumber {
@@ -878,7 +879,9 @@ impl SealedPin for AnyPin {
 foreach_pin!(
     ($pin_name:ident, $port_name:ident, $port_num:expr, $pin_num:expr, $exti_ch:ident) => {
         impl Pin for peripherals::$pin_name {
-            #[cfg(feature = "exti")]
+        }
+        #[cfg(feature = "exti")]
+        impl ExtiPin for peripherals::$pin_name {
             type ExtiChannel = peripherals::$exti_ch;
         }
         impl SealedPin for peripherals::$pin_name {

embassy-stm32/src/lib.rs

@@ -153,7 +153,7 @@ pub use crate::_generated::interrupt;
 /// Macro to bind interrupts to handlers.
 ///
 /// This defines the right interrupt handlers, and creates a unit struct (like `struct Irqs;`)
-/// and implements the right [`Binding`]s for it. You can pass this struct to drivers to
+/// and implements the right [`Binding`](crate::interrupt::typelevel::Binding)s for it. You can pass this struct to drivers to
 /// prove at compile-time that the right interrupts have been bound.
 ///
 /// Example of how to bind one interrupt:
@@ -180,6 +180,10 @@ pub use crate::_generated::interrupt;
 ///     }
 /// );
 /// ```
+///
+/// Some chips collate multiple interrupt signals into a single interrupt vector. In the above example, I2C2_3 is a
+/// single vector which is activated by events and errors on both peripherals I2C2 and I2C3. Check your chip's list
+/// of interrupt vectors if you get an unexpected compile error trying to bind the standard name.
 // developer note: this macro can't be in `embassy-hal-internal` due to the use of `$crate`.
 #[macro_export]
 macro_rules! bind_interrupts {

examples/boot/application/stm32f3/src/bin/a.rs

@@ -6,12 +6,18 @@ use defmt_rtt::*;
 use embassy_boot_stm32::{AlignedBuffer, FirmwareUpdater, FirmwareUpdaterConfig};
 use embassy_embedded_hal::adapter::BlockingAsync;
 use embassy_executor::Spawner;
-use embassy_stm32::exti::ExtiInput;
+use embassy_stm32::exti::{self, ExtiInput};
 use embassy_stm32::flash::{Flash, WRITE_SIZE};
 use embassy_stm32::gpio::{Level, Output, Pull, Speed};
+use embassy_stm32::{bind_interrupts, interrupt};
 use embassy_sync::mutex::Mutex;
 use panic_reset as _;
 
+bind_interrupts!(
+    pub struct Irqs{
+        EXTI15_10 => exti::InterruptHandler<interrupt::typelevel::EXTI15_10>;
+});
+
 #[cfg(feature = "skip-include")]
 static APP_B: &[u8] = &[0, 1, 2, 3];
 #[cfg(not(feature = "skip-include"))]
@@ -23,7 +29,7 @@ async fn main(_spawner: Spawner) {
     let flash = Flash::new_blocking(p.FLASH);
     let flash = Mutex::new(BlockingAsync::new(flash));
 
-    let mut button = ExtiInput::new(p.PC13, p.EXTI13, Pull::Up);
+    let mut button = ExtiInput::new(p.PC13, p.EXTI13, Pull::Up, Irqs);
 
     let mut led = Output::new(p.PA5, Level::Low, Speed::Low);
     led.set_high();