/* libhw/rp2040_gpioirq.h - Utilities for sharing the GPIO IRQ (IO_IRQ_BANK0)
 *
 * Copyright (C) 2025  Luke T. Shumaker <lukeshu@lukeshu.com>
 * SPDX-License-Identifier: AGPL-3.0-or-later
 */

#ifndef _LIBHW_RP2040_GPIOIRQ_H_
#define _LIBHW_RP2040_GPIOIRQ_H_

#include <hardware/gpio.h> /* for enum gpio_irq_level */

typedef void (*gpioirq_handler_t)(void *arg, uint gpio, enum gpio_irq_level event);

/**
 * Register `fn(arg, ...)` to be called when `event` fires on GPIO pin
 * `gpio`.
 *
 * If multiple events happen close together, the handlers will not
 * necessarily be called in-order.
 *
 * Your handler does not need to acknowledge the IRQ; that will be
 * done for you after your handler is called.
 *
 * It is illegal to call gpioirq_set_and_enable_exclusive_handler()
 * on multiple cores.
 *
 * This is better than the Pico-SDK <hardware/gpio.h> IRQ functions
 * because their functions call the handlers for every event, and it
 * is up to you to de-mux them in your handler.
 */
void gpioirq_set_and_enable_exclusive_handler(uint gpio, enum gpio_irq_level event, gpioirq_handler_t fn, void *arg);

#endif /* _LIBHW_RP2040_GPIOIRQ_H_ */