include/zephyr/drivers/interrupt_controller/intc_esp32.h

/*
 * Copyright (c) 2021 Espressif Systems (Shanghai) Co., Ltd.
 *
 * SPDX-License-Identifier: Apache-2.0
 */

#ifndef ZEPHYR_INCLUDE_DRIVERS_ESP_INTR_ALLOC_H__
#define ZEPHYR_INCLUDE_DRIVERS_ESP_INTR_ALLOC_H__

#include <stdint.h>
#include <stdbool.h>

/* number of possible interrupts per core */
#define ESP_INTC_INTS_NUM		(32)

/*
 * Interrupt allocation flags - These flags can be used to specify
 * which interrupt qualities the code calling esp_intr_alloc* needs.
 *
 */

/* Keep the LEVELx values as they are here; they match up with (1<<level) */
#define ESP_INTR_FLAG_LEVEL1		(1<<1)	/* Accept a Level 1 int vector, lowest priority */
#define ESP_INTR_FLAG_LEVEL2		(1<<2)	/* Accept a Level 2 int vector */
#define ESP_INTR_FLAG_LEVEL3		(1<<3)	/* Accept a Level 3 int vector */
#define ESP_INTR_FLAG_LEVEL4		(1<<4)	/* Accept a Level 4 int vector */
#define ESP_INTR_FLAG_LEVEL5		(1<<5)	/* Accept a Level 5 int vector */
#define ESP_INTR_FLAG_LEVEL6		(1<<6)	/* Accept a Level 6 int vector */
#define ESP_INTR_FLAG_NMI		(1<<7)	/* Accept a Level 7 int vector, highest priority */
#define ESP_INTR_FLAG_SHARED		(1<<8)	/* Interrupt can be shared between ISRs */
#define ESP_INTR_FLAG_EDGE		(1<<9)	/* Edge-triggered interrupt */
#define ESP_INTR_FLAG_IRAM		(1<<10)	/* ISR can be called if cache is disabled */
#define ESP_INTR_FLAG_INTRDISABLED	(1<<11)	/* Return with this interrupt disabled */

/* Low and medium prio interrupts. These can be handled in C. */
#define ESP_INTR_FLAG_LOWMED	(ESP_INTR_FLAG_LEVEL1|ESP_INTR_FLAG_LEVEL2|ESP_INTR_FLAG_LEVEL3)

/* High level interrupts. Need to be handled in assembly. */
#define ESP_INTR_FLAG_HIGH	(ESP_INTR_FLAG_LEVEL4|ESP_INTR_FLAG_LEVEL5|ESP_INTR_FLAG_LEVEL6| \
				 ESP_INTR_FLAG_NMI)

/* Mask for all level flags */
#define ESP_INTR_FLAG_LEVELMASK	(ESP_INTR_FLAG_LEVEL1|ESP_INTR_FLAG_LEVEL2|ESP_INTR_FLAG_LEVEL3| \
				 ESP_INTR_FLAG_LEVEL4|ESP_INTR_FLAG_LEVEL5|ESP_INTR_FLAG_LEVEL6| \
				 ESP_INTR_FLAG_NMI)

/*
 * The esp_intr_alloc* functions can allocate an int for all *_INTR_SOURCE int sources that
 * are routed through the interrupt mux. Apart from these sources, each core also has some internal
 * sources that do not pass through the interrupt mux. To allocate an interrupt for these sources,
 * pass these pseudo-sources to the functions.
 */
#define ETS_INTERNAL_TIMER0_INTR_SOURCE         -1 /* Xtensa timer 0 interrupt source */
#define ETS_INTERNAL_TIMER1_INTR_SOURCE         -2 /* Xtensa timer 1 interrupt source */
#define ETS_INTERNAL_TIMER2_INTR_SOURCE         -3 /* Xtensa timer 2 interrupt source */
#define ETS_INTERNAL_SW0_INTR_SOURCE            -4 /* Software int source 1 */
#define ETS_INTERNAL_SW1_INTR_SOURCE            -5 /* Software int source 2 */
#define ETS_INTERNAL_PROFILING_INTR_SOURCE      -6 /* Int source for profiling */

/* Function prototype for interrupt handler function */
typedef void (*intr_handler_t)(void *arg);

struct shared_vector_desc_t {
	int disabled : 1;
	int source : 8;
	volatile uint32_t *statusreg;
	uint32_t statusmask;
	intr_handler_t isr;
	void *arg;
	struct shared_vector_desc_t *next;
};

/* Pack using bitfields for better memory use */
struct vector_desc_t {
	int flags : 16;                                 /* OR of VECDESC_FLAG_* defines */
	unsigned int cpu : 1;
	unsigned int intno : 5;
	int source : 8;                                 /* Int mux flags, used when not shared */
	struct shared_vector_desc_t *shared_vec_info;   /* used when VECDESC_FL_SHARED */
	struct vector_desc_t *next;
};

/** Interrupt handler associated data structure */
struct intr_handle_data_t {
	struct vector_desc_t *vector_desc;
	struct shared_vector_desc_t *shared_vector_desc;
};

/**
 * @brief Initializes interrupt table to its defaults
 */
void esp_intr_initialize(void);

/**
 * @brief Mark an interrupt as a shared interrupt
 *
 * This will mark a certain interrupt on the specified CPU as
 * an interrupt that can be used to hook shared interrupt handlers
 * to.
 *
 * @param intno The number of the interrupt (0-31)
 * @param cpu CPU on which the interrupt should be marked as shared (0 or 1)
 * @param is_in_iram Shared interrupt is for handlers that reside in IRAM and
 *                   the int can be left enabled while the flash cache is disabled.
 *
 * @return -EINVAL if cpu or intno is invalid
 *         0 otherwise
 */
int esp_intr_mark_shared(int intno, int cpu, bool is_in_iram);

/**
 * @brief Reserve an interrupt to be used outside of this framework
 *
 * This will mark a certain interrupt on the specified CPU as
 * reserved, not to be allocated for any reason.
 *
 * @param intno The number of the interrupt (0-31)
 * @param cpu CPU on which the interrupt should be marked as shared (0 or 1)
 *
 * @return -EINVAL if cpu or intno is invalid
 *         0 otherwise
 */
int esp_intr_reserve(int intno, int cpu);

/**
 * @brief Allocate an interrupt with the given parameters.
 *
 * This finds an interrupt that matches the restrictions as given in the flags
 * parameter, maps the given interrupt source to it and hooks up the given
 * interrupt handler (with optional argument) as well. If needed, it can return
 * a handle for the interrupt as well.
 *
 * The interrupt will always be allocated on the core that runs this function.
 *
 * If ESP_INTR_FLAG_IRAM flag is used, and handler address is not in IRAM or
 * RTC_FAST_MEM, then ESP_ERR_INVALID_ARG is returned.
 *
 * @param source The interrupt source. One of the *_INTR_SOURCE interrupt mux
 *               sources, as defined in esp-xtensa-intmux.h, or one of the internal
 *               ETS_INTERNAL_*_INTR_SOURCE sources as defined in this header.
 * @param flags An ORred mask of the ESP_INTR_FLAG_* defines. These restrict the
 *               choice of interrupts that this routine can choose from. If this value
 *               is 0, it will default to allocating a non-shared interrupt of level
 *               1, 2 or 3. If this is ESP_INTR_FLAG_SHARED, it will allocate a shared
 *               interrupt of level 1. Setting ESP_INTR_FLAG_INTRDISABLED will return
 *               from this function with the interrupt disabled.
 * @param handler The interrupt handler. Must be NULL when an interrupt of level >3
 *               is requested, because these types of interrupts aren't C-callable.
 * @param arg    Optional argument for passed to the interrupt handler
 * @param ret_handle Pointer to a struct intr_handle_data_t pointer to store a handle that can
 *               later be used to request details or free the interrupt. Can be NULL if no handle
 *               is required.
 *
 * @return -EINVAL if the combination of arguments is invalid.
 *         -ENODEV No free interrupt found with the specified flags
 *         0 otherwise
 */
int esp_intr_alloc(int source,
		int flags,
		intr_handler_t handler,
		void *arg,
		struct intr_handle_data_t **ret_handle);


/**
 * @brief Allocate an interrupt with the given parameters.
 *
 *
 * This essentially does the same as esp_intr_alloc, but allows specifying a register and mask
 * combo. For shared interrupts, the handler is only called if a read from the specified
 * register, ANDed with the mask, returns non-zero. By passing an interrupt status register
 * address and a fitting mask, this can be used to accelerate interrupt handling in the case
 * a shared interrupt is triggered; by checking the interrupt statuses first, the code can
 * decide which ISRs can be skipped
 *
 * @param source The interrupt source. One of the *_INTR_SOURCE interrupt mux
 *               sources, as defined in esp-xtensa-intmux.h, or one of the internal
 *               ETS_INTERNAL_*_INTR_SOURCE sources as defined in this header.
 * @param flags An ORred mask of the ESP_INTR_FLAG_* defines. These restrict the
 *               choice of interrupts that this routine can choose from. If this value
 *               is 0, it will default to allocating a non-shared interrupt of level
 *               1, 2 or 3. If this is ESP_INTR_FLAG_SHARED, it will allocate a shared
 *               interrupt of level 1. Setting ESP_INTR_FLAG_INTRDISABLED will return
 *               from this function with the interrupt disabled.
 * @param intrstatusreg The address of an interrupt status register
 * @param intrstatusmask A mask. If a read of address intrstatusreg has any of the bits
 *               that are 1 in the mask set, the ISR will be called. If not, it will be
 *               skipped.
 * @param handler The interrupt handler. Must be NULL when an interrupt of level >3
 *               is requested, because these types of interrupts aren't C-callable.
 * @param arg    Optional argument for passed to the interrupt handler
 * @param ret_handle Pointer to a struct intr_handle_data_t pointer to store a handle that can
 *               later be used to request details or free the interrupt. Can be NULL if no handle
 *               is required.
 *
 * @return -EINVAL if the combination of arguments is invalid.
 *         -ENODEV No free interrupt found with the specified flags
 *         0 otherwise
 */
int esp_intr_alloc_intrstatus(int source,
		int flags,
		uint32_t intrstatusreg,
		uint32_t intrstatusmask,
		intr_handler_t handler,
		void *arg,
		struct intr_handle_data_t **ret_handle);


/**
 * @brief Disable and free an interrupt.
 *
 * Use an interrupt handle to disable the interrupt and release the resources associated with it.
 * If the current core is not the core that registered this interrupt, this routine will be
 * assigned to the core that allocated this interrupt, blocking and waiting until the resource
 * is successfully released.
 *
 * @note
 * When the handler shares its source with other handlers, the interrupt status bits
 * it's responsible for should be managed properly before freeing it. See ``esp_intr_disable``
 * for more details. Please do not call this function in ``esp_ipc_call_blocking``.
 *
 * @param handle The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
 *
 * @return -EINVAL the handle is NULL
 *         0 otherwise
 */
int esp_intr_free(struct intr_handle_data_t *handle);


/**
 * @brief Get CPU number an interrupt is tied to
 *
 * @param handle The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
 *
 * @return The core number where the interrupt is allocated
 */
int esp_intr_get_cpu(struct intr_handle_data_t *handle);

/**
 * @brief Get the allocated interrupt for a certain handle
 *
 * @param handle The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
 *
 * @return The interrupt number
 */
int esp_intr_get_intno(struct intr_handle_data_t *handle);

/**
 * @brief Disable the interrupt associated with the handle
 *
 * @note
 * 1. For local interrupts (ESP_INTERNAL_* sources), this function has to be called on the
 * CPU the interrupt is allocated on. Other interrupts have no such restriction.
 * 2. When several handlers sharing a same interrupt source, interrupt status bits, which are
 * handled in the handler to be disabled, should be masked before the disabling, or handled
 * in other enabled interrupts properly. Miss of interrupt status handling will cause infinite
 * interrupt calls and finally system crash.
 *
 * @param handle The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
 *
 * @return -EINVAL if the combination of arguments is invalid.
 *         0 otherwise
 */
int esp_intr_disable(struct intr_handle_data_t *handle);

/**
 * @brief Enable the interrupt associated with the handle
 *
 * @note For local interrupts (ESP_INTERNAL_* sources), this function has to be called on the
 *       CPU the interrupt is allocated on. Other interrupts have no such restriction.
 *
 * @param handle The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
 *
 * @return -EINVAL if the combination of arguments is invalid.
 *         0 otherwise
 */
int esp_intr_enable(struct intr_handle_data_t *handle);

/**
 * @brief Set the "in IRAM" status of the handler.
 *
 * @note Does not work on shared interrupts.
 *
 * @param handle The handle, as obtained by esp_intr_alloc or esp_intr_alloc_intrstatus
 * @param is_in_iram Whether the handler associated with this handle resides in IRAM.
 *                   Handlers residing in IRAM can be called when cache is disabled.
 *
 * @return -EINVAL if the combination of arguments is invalid.
 *         0 otherwise
 */
int esp_intr_set_in_iram(struct intr_handle_data_t *handle, bool is_in_iram);

/**
 * @brief Disable interrupts that aren't specifically marked as running from IRAM
 */
void esp_intr_noniram_disable(void);


/**
 * @brief Re-enable interrupts disabled by esp_intr_noniram_disable
 */
void esp_intr_noniram_enable(void);

#endif