/*
* 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