Support GPIO input interrupts

[mciantyre]

The 0.4 HAL does not have any way to support interrupts on GPIO inputs. This also applies to any previous version of imxrt-hal. Add and document an API that supports

• enabling / disabling interrupts on a GPIO input
• selecting the various edge / level configurations

Since this should be a brand-new feature, it should be possible to release in 0.4.5 without issues.

[mciantyre]

There's a proof-of-concept in the prototype imxrt-async-hal. This method shows one way of setting the interrupt configuration (called a "trigger"). That method might be ported here without too much changing.

[algesten]

@mciantyre I'm happy to look into providing a PR. You kindly offered to mentor me, thanks!!! Just be warned that although I did hack 68000 assembler back in the 90s, I'm completely new to this microcontroller world. The three-letter acronyms do make my head spin at times.

Given the async example above, I understand which registers to modify in the ral. What is unclear to me is:

• Would the user of teensy4-bsp register the ISR using [cortex_m_rt::interrupt] or do we do that for them? You say "...there's one ISR for every 16 GPIOs" (like GPIO4_Combined_16_31), I assume that means you get on interrupt for any of 16 pins. When interrupt fires, would we figure out which pin it concerned and dispatch to a per-pin provided ISR, or would we provide an API to figure out the pin that fired?

This is from the ral interrupts:

    GPIO1_INT0,
    GPIO1_INT1,
    GPIO1_INT2,
    GPIO1_INT3,
    GPIO1_INT4,
    GPIO1_INT5,
    GPIO1_INT6,
    GPIO1_INT7,
    GPIO1_Combined_0_15,
    GPIO1_Combined_16_31,
    GPIO2_Combined_0_15,
    GPIO2_Combined_16_31,
    GPIO3_Combined_0_15,
    GPIO3_Combined_16_31,
    GPIO4_Combined_0_15,
    GPIO4_Combined_16_31,
    GPIO5_Combined_0_15,
    GPIO5_Combined_16_31,

• Now I understand the GPIO1_Combined_0_15 etc, but what are the GPIO1_INT0...?

It would be very helpful if we could sketch out (in pseudocode) the surface API in imxrt-hal (and maybe also teensy4-bsp if there's a level of abstraction there), and I can then figure out the in-between.

[mciantyre]

Would the user of teensy4-bsp register the ISR using [cortex_m_rt::interrupt] or do we do that for them?

To get started, let's require that the BSP or HAL end-user implements the interrupt with #[cortex_m_rt::interrupt]. The user will figure out which GPIO triggered, respond, and clear the interrupt. This will keep our implementation easier, and expose all the capabilities to the end user. We can revisit per-pin dispatch later, or build it separately and generally.

Now I understand the GPIO1_Combined_0_15 etc, but what are the GPIO1_INT0...?

For i.MX RT chips in the 1060 family, the first eight pins of GPIO1 can dispatch to a dedicated ISR. These eight interrupts complement what would also be signaled through GPIO1_Combined_0_15.

However, these interrupts aren't available on all i.MX RT chips. Take a look at the 1011 interrupts to see a chip variant that doesn't support anything like this. (Today's HAL is focused on the 1060, so this is just a note for the future.)

Additionally, the 1060 has the GPIO6_7_8_9 interrupt, sitting at the back of the vector table. When GPIOs are configured for fast mode, they'll trigger that interrupt, which handles up to 32 * 4 GPIO inputs. This also isn't supported on all i.MX RT chips. But, we'll need to handle the transitions from normal to fast GPIO modes when considering interrupt configurations.

It would be very helpful if we could sketch out (in pseudocode) the surface API in imxrt-hal (and maybe also teensy4-bsp if there's a level of abstraction there)

I think these five GPIO input methods would be all we need:

/// GPIO input interrupt configurations.
///
/// These configurations do not take effect until
/// GPIO input interrupts are enabled.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u32)]
pub enum InterruptConfiguration {
    LowLevelSensitive = 0,
    HighLevelSensitive = 1,
    RisingEdgeSensitive = 2,
    FallingEdgeSensitive = 3,
    EitherEdgeSensitive = 4,
}

impl<P> GPIO<P, Input>
where
    P: Pin,
{
    /// Enable (`true`) or disable (`false`) interrupts for this
    /// GPIO input
    pub fn set_interrupt_enable(&mut self, enable: bool) { /* ... */ }

    /// Indicates if interrupts are (`true`) or are not (`false`)
    /// enabled for this GPIO input
    pub fn is_interrupt_enabled(&self) -> bool { /* ... */  }

    /// Set the interrupt configuration for this GPIO input
    pub fn set_interrupt_configuration(&mut self, interrupt_configuration: InterruptConfiguration) { /* ... */ }

    /// Indicates if this GPIO input triggered an interrupt.
    pub fn is_interrupt_status(&self) -> bool { /* ... */ }

    /// Clear the interrupt status flag.
    pub fn clear_interrupt_status(&mut self) { /* ... */ }
}

with usage in a BSP resembling

use cortex_m::interrupt::{self, Mutex};
use core::cell::RefCell;
use imxrt_hal::gpio::{GPIO, Input, InterruptConfiguration};

type InputPin = GPIO<Input, /* Pad that maps to GPIO1_18... */>;

static INPUT_PIN: Mutex<RefCell<Optional<InputPin>>> = Mutex::new(RefCell::new(None));

#[cortex_m_rt::interrupt]
fn GPIO1_Combined_16_31() {
    interrupt::free(|cs| {
        let input = INPUT_PIN.borrow(cs);
        let mut input = input.borrow_mut();
        let input = input.as_mut().unwrap();

        if input.is_interrupt_status() {
            // This pin triggered! Do something here...
            input.clear_interupt_status();
        }
    });
}

#[cortex_m_rt::entry]
fn main() -> ! {
    // Get peripherals...
    // Set up pins...
    // Set up GPIO1_18...
    gpio1_18.set_interrupt_configuration(InterruptConfiguration::RisingEdgeSensitive);
    gpio1_18.set_interrupt_enable(true);
    // Move gpio1_18 into INPUT_PIN mutex...
    // Unmask GPIO1_Combined_16_31 in NVIC...
    loop { /* Do things, wait for interrupt */ }
}

[algesten]

@mciantyre Thanks for the guidance. That all makes sense. I've taken a first stab at the PR, but for some reason I can't get it to work just yet. Maybe there is some obviously problem you spot?

If it all looks good, I'll continue testing and debugging it. Here's my test code.

type InputPin = GPIO<P6, Input>;

fn setup_gpio_interrupt(mut pin: InputPin) {
    static INPUT_PIN: Mutex<RefCell<Option<InputPin>>> = Mutex::new(RefCell::new(None));

    #[cortex_m_rt::interrupt]
    fn GPIO1_Combined_0_15() {
        cortex_m::interrupt::free(|cs| {
            info!("interrupt!");

            INPUT_PIN.borrow(cs).borrow_mut().as_mut().map(|pin| {
                info!("Is interrupt: {}", pin.is_interrupt_status());
                pin.clear_interrupt_status();
            });
        });
    }

    cortex_m::interrupt::free(|cs| {
        pin.set_interrupt_configuration(InterruptConfiguration::RisingEdgeSensitive);
        pin.set_interrupt_enable(true);

        *INPUT_PIN.borrow(cs).borrow_mut() = Some(pin);

        unsafe { cortex_m::peripheral::NVIC::unmask(bsp::interrupt::GPIO1_Combined_0_15) };
    });
}

Things I'm unsure about:

• P6 is B0_10, which I hope is in GPIO1_Combined_0_15, is that so?
• I've added a pull-down resistor to GND on P6, is that needed?
• Does the order of set_interrupt_configuration and set_interrupt_enable matter?
• A few questions in the PR as well.

[mciantyre]

The setup_gpio_interrupt function looks good! Great use of scoping.

P6 is B0_10, which I hope is in GPIO1_Combined_0_15, is that so?

Pin 6 on the Teensy 4 is B0_10. But, B0_10 is GPIO2_6. Our function is registering a GPIO1 interrupt. This might be why we're seeing issues. We could try to change the interrupt to GPIO2_Combined_0_15.

There's two ways to correlate a pad to a GPIO:

• Check the reference manual. Chapter 10 of the i.MX RT 1060 reference manual has a table of pads to functions. To source the reference manual, check the contributing guide.
• We can use the imxrt-iomuxc crate's documentation. Browse to the gpio::Pin documentation, and scroll down to see the implementors. Expand the implementation for B0_06, and it reveals the GPIO implementation.

I've added a pull-down resistor to GND on P6, is that needed?

Depends on the rest of the circuit. The imxrt-iomuxc crate provides the pin configuration API if you'd like to change the pin's internal settings.

When prototyping in the imxrt-async-hal crate, I wired Teensy 4 pins directly together without changing the pad configurations. Worked for prototyping, but I might have been lucky.

Does the order of set_interrupt_configuration and set_interrupt_enable matter?

As written in the critical section, the order shouldn't matter. Without the critical section, we'll need to consider if the enable call could immediately trigger an interrupt before we could set the configuration, and if that's OK.

[algesten]

@mciantyre thanks! That makes sense.

I've made amends in the PR based on your feedback, and two more questions popped up (see PR).

I understand how to get from pin to interrupt now, however it's a bit opaque. Maybe we can make a point of documenting that well in the example we land after this PR?

The breadboard is currently stashed away (I rage quit after failing to get this I/O expander chip to talk SPI with me), but it's coming out in a couple of days, I'll rig and test the interrupt code then.

[algesten]

So, I got the breadboard up again, and there's some progress.

I tested using Pin6 with GPIO2_Combined_0_15 and also Pin20 which I believe is GPIO1_Combined_16_31. Both with similar result. I have the pin with external pull-down to GND (4.7K) and then use a 3.3V lead to touch it.

• For EitherEdge, it seems to work. It fires both when touching and removing - often more than once which I assume is because I don't make a perfect immediate connection.
• For any other edge config, the ISR is just constantly firing until I touch the pin with 3.3V, in which case it pauses.

I assume I got some error in the set_interrupt_configuration - I need to dig into that more tomorrow. See if I can understand the reference manual on this.

[algesten]

Actually. I just figured it out. Test error. All works well!

[algesten]

The only thing left to test in that PR is the fast switching. I'll do that tomorrow.