Relationship between GPIO ports and Teensy pins

[dannymcgee]

Hi there! I'm quite new to embedded development outside of the Arduino/Teensyduino framework, and one thing that's been a source of confusion is the difference between GPIO ports and pins, which pins correspond to which GPIO ports, and which member of imxrt____::Interrupt I need to bind RTIC tasks to. For example, I was trying to test the waters by plugging in a button that would light up the onboard LED when pressed, and I eventually stumbled my way into a solution, but I don't think I really understand it:

#![no_std]
#![no_main]

use teensy4_panic as _;

#[rtic::app(device = teensy4_bsp, peripherals = false)]
mod app {
    use bsp::{
        board,
        hal::{
            gpio,
            iomuxc::{self, Config, Hysteresis, PullKeeper},
        },
    };
    use teensy4_bsp as bsp;

    #[shared]
    struct Shared {}

    #[local]
    struct Local {
        led: board::Led,
        button: gpio::Input<bsp::pins::t40::P4>,
    }

    #[init]
    fn init(_: init::Context) -> (Shared, Local, init::Monotonics) {
        let instances = board::instances();
        let board::Resources {
            mut pins,
            mut gpio2,
            mut gpio4,
            ..
        } = board::t40(instances);

        let led = board::led(&mut gpio2, pins.p13);

        iomuxc::configure(
            &mut pins.p4,
            Config::zero()
                .set_hysteresis(Hysteresis::Enabled)
                .set_pull_keeper(Some(PullKeeper::Pullup100k)),
        );
        let button = gpio4.input(pins.p4);
        gpio4.set_interrupt(&button, Some(gpio::Trigger::EitherEdge));

        (Shared {}, Local { led, button }, init::Monotonics())
    }

    #[task(binds = GPIO4_COMBINED_0_15, local = [led, button])]
    fn on_button_change(cx: on_button_change::Context) {
        let on_button_change::LocalResources { led, button } = cx.local;

        if button.is_set() {
            led.clear()
        } else {
            led.set();
        }

        button.clear_triggered();
    }
}

At first I tried gpio2.input(pins.p2), but I got a fairly cryptic error about trait bounds being unsatisfied. So I tried gpio2.input(pins.p4), and got the same error. Finally I tried gpio4.input(pins.p4), and the squiggles went away. My first thought was that maybe GPIO ports correspond 1:1 with pins (and GPIO2<->pin13 is an anomaly because it's the onboard LED), but then I noticed there are only 4 GPIO ports on the Resources struct.

Then I tried creating the interrupt task, first by just blindly trying #[task(binds = P4, ...)]. That gave me an error that P4 is not a member of the Interrupts enum, which at least told me what scope those magic names in the examples come from. But then I looked at the enum definition and my brain melted a little. GPIO4_COMBINED_0_15 was a shot in the dark that worked (I set the interrupt via gpio4, and pin 4 is within the range of 0_15, so... profit?), but there's also a GPIO2_COMBINED_0_15, and given that gpio2.input(pins.p2) didn't work, there must be a whole lot that I'm missing here.

Are there any resources that could help me get a grasp on these things? I scanned over the Rust Embedded Book before I got started, but I don't have either of the example boards that was written for, and anyway it wouldn't help me resolve the Teensy-specific confusions. I don't see any references to "GPIO" on the Teensy 4.0 page, but I do see a handful of NVCC_GPIO labels on the schematic — do I need to read the microcontroller datasheet and cross-reference that with the Teensy schematic... somehow? Or is there a table somewhere that's easier to follow?

Update

On further investigation, the GPIO port number and pin number do need to match because of how the Port::input function is typed. But that can't be correct, can it? If I'm reading the table here correctly (which, incidentally, is exactly what I was asking for above 🙂), then the only pins for which gpio_.input(pins.p_) would actually work are pins 1 and 4, since those happen to be on the GPIO1 and GPIO4 ports.

Update 2

Nope, nevermind, gpio4.input(pins.p2) totally works, just like the table implies it should. So then my only remaining question is about the Interrupts enum — should I use GPIOx_COMBINED_y_z where x is the GPIO port listed on the table for that pin, and y <= pin <= z? Will the same task be invoked if I add interrupts to different pins that correspond to the same interrupt ID?

[mciantyre]

Great job working through this, and thanks for sharing your findings.

Sounds like you're correctly interpreting the (common) pin table. But for future readers, here's what we're talking about: Scan down the left-most Pin column to find board pin 4. Then, scan the row until you find GPIO4_IO06 in one of the columns (ignore the "pad ID" column). The GPIO4_IO06 entry indicates that pin 4 works with GPIO port 4. Its offset is 6. This explains why the board pin 4 object pins.p4 only works with gpio4 and not gpio2.

(I'm using the term "offset" to not overload the term "pin." Sometimes it's denoted like GPIO4[6], which looks like an array offset.)

GPIO4_COMBINED_0_15 will pend whenever something interesting happens on a input of port 4, offsets 0 through 15. Since board pin 4 is GPIO port 4, offset 6, this all works. 0 <= 6 <= 15.

Will the same task be invoked if I add interrupts to different pins that correspond to the same interrupt ID?

That's right. You'll need to check the GPIO inputs that you configured to figure out which one actually activated. So if board pin 2 (GPIO4[4]) were also configured to trigger an interrupt, that same GPIO4_COMBINED_0_15 interrupt would activate.

If you really need a 1:1 mapping of interrupt to GPIO input, know that the first eight offsets of GPIO port 1 have dedicated interrupts. Teensy board pins 0 and 1 are candidates for this feature. The interrupt is named like this.