/* * Copyright (c) 2021 Espressif Systems (Shanghai) Co., Ltd. * * SPDX-License-Identifier: Apache-2.0 */ #ifndef ZEPHYR_INCLUDE_DRIVERS_INTERRUPT_CONTROLLER_INTC_ESP32_H_ #define ZEPHYR_INCLUDE_DRIVERS_INTERRUPT_CONTROLLER_INTC_ESP32_H_ #include #include /* 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< 0 ? ((1 << (priority)) & ESP_INTR_FLAG_LEVELMASK) : 0) /* * Check interrupt flags from input and filter unallowed values. */ #define ESP_INT_FLAGS_CHECK(int_flags) ((int_flags) & ESP_INTR_FLAG_SHARED) /* * 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 /* ZEPHYR_INCLUDE_DRIVERS_INTERRUPT_CONTROLLER_INTC_ESP32_H_ */