The `Io` struct has multiple constructors which makes it confusing to use correctly

[jessebraham]

As a workaround, in #1861 the Io::new_no_bind_interrupt constructor was added to allow initializing the Io struct without binding the GPIO interrupt.

This is a bit of a footgun, and is too easy to mess up. We should try to find a better way to handle this scenario.

[bjoernQ]

IIRC correctly this driver is a bit different than all the others because we want people to easily mix async and their own ISR - if we still think this is something we want to support and do by default I'm not sure how to solve this

• Add more documentation? Probably won't help?
• Remove that constructor and explain (in docs) how to unsafely override the interrupt-handler and tell them they should forget about using async then? (Would make the default use-case less confusing but your special use-case more of a pain)

Maybe there are other options I just can't think of right now

[bugadani]

Can we allow per-pin ISR binding (i.e. similar to how we bind interrupts currently, put function pointers into a big table)? Would that help here?

[Dominaezzz]

Input could be changed to accept Async/Blocking in its type signature, then users can do Input::new() or Input::new_async(). This solves the "can this pin async or not" problem.

Then an additional parameter to Input::new_async would be a type that represents "I pinky promise I'm calling the handler for this pin". (Something along the lines of https://docs.embassy.dev/embassy-stm32/git/stm32f100rc/macro.bind_interrupts.html). This forces the user to be aware of what they're doing.

Then maybe this "pinky promise" type can be easily acquired by either calling Io::new_async or using an unsafe ctor?
The documentation for the unsafe ctor can say something like, you must call handle_gpio_interrupt.

For the easy/common path, I'm picturing code that looks like this.

let io = Io::new_async(peripherals.GPIO, peripherals.IO_MUX);

let button = Input::new_async(io.pins.gpio7, Pull::Up, io.handler); // name pending bikeshed

Then for the uncommon path.

let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);

let handler = unsafe { GpioHandlerRegisteration::new() }; // name pending bikeshed
let button = Input::new_async(io.pins.gpio7, Pull::Up, handler);

[bugadani]

Why would you allow overriding the handler of the async API? Why would you require the async api to allow registering an irq handler? And thirdly, why would you need unsafe code for this? We can add an unsafe way to override the global handler, sure, but this is some unnecessary complication on the per-pin API.

[Dominaezzz]

Why would you allow overriding the handler of the async API?

What do you mean? In my comment I described an "either or" situation.

• Either you give ownership of the handler registration to the hal and get async,
• Or you set up your own handler, and you can opt-in to the async API of a pin if you promise to call the hal's handler.

Why would you require the async api to allow registering an irq handler?

I was trying to allow mixing of both async and custom irq.

And thirdly, why would you need unsafe code for this?

To raise some eyebrows. I agree it's not strictly necessary. Having your async program hang is perfectly sound Rust.

We can add an unsafe way to override the global handler, sure, but this is some unnecessary complication on the per-pin API.

I suppose that works. It ensures that users are aware of the fact that the async API won't work as expected if the handler is overridden.
The only minor peeve I have with this is registering a handler shouldn't be an unsafe operation. It's safe everywhere else within the HAL.
Also to you third point, this way uses unsafe too 😛 .

[bugadani]

So what I have in mind:

• Allow unsafely replacing the global irq handler by calling io.set_interrupt_handler. This needs to be done before moving out the first pin, so it's not possible to do once pins are in use.
• Modify the default handler into an array of handler functions. This way we can freely attach/detach irq handlers to specific pins.
• Do not allow replacing the irq handler of an async pin (at least not safely).

This is simple as it has sane defaults, at least as far as my midnight brain is concerned. This is also flexible as we can mix and match async pins with blocking pins + irq handlers. There may be a slight perf hit caused by the fn table, but if the default handlers are in RAM, it shouldn't be too bad?

What am I missing?

[bjoernQ]

These are all very good ideas 👍 However I think the original problem with RTIC is this one:

To handle the GPIO interrupt they generate a function unsafe extern "C" fn GPIO(...) to replace https://github.com/esp-rs/esp-pacs/blob/c717453df31e5f37c48edd287906bbf09aa82112/esp32c3/src/lib.rs#L114 at compile time

In the constructor the GPIO driver changes that handler address - so their implementation won't get called

So maybe all it needs would be to use https://docs.esp-rs.org/esp-hal/esp-hal/0.20.0/esp32c3/esp_hal/interrupt/fn.bind_interrupt.html to replace the handler after creating the driver in RTIC (no need for the additional constructor then)?

Or they could use https://docs.esp-rs.org/esp-hal/esp-hal/0.20.0/esp32c3/esp_hal/interrupt/fn.enable_direct.html since they want direct vectoring 🤔

But I have to admit I don't know enough about RTIC - I think last time I tried to use it was when it still was named RTFM

[bugadani]

This also means that RTIC, when it sits on the GPIO interrupt, is incompatible with a significant portion of our API (any async GPIO, any GPIO interrupt handling). How can we teach the users about this?

[bugadani]

We can add a bind_io_interrupts: IoInterrupt to esp_hal::Config where IoInterrupt is an enum and move the IO_MUX initialisation into esp_hal::init. That way we can remove Io::new completely and just expose the pins to the user.

enum IoInterrupt {
    DoNotBind,
    Default(Priority),
    User(InterruptHandler)
}

[bjoernQ]

I think I would like to have it initialized in esp_hal::init given 99.9% of all real-world use-cases will need at least some pins.

Users will still need to know when to do what but the enum is definitely more intuitive than a weird named second constructor.

And while writing this, even if we don't want to move initialization to esp_hal::init the constructor could take that enum.
Only "downside" would be Io won't implement InterruptConfigurable anymore but not sure that would be a real issue